W3C

Web Services Event Descriptions (WS-EventDescriptions)

W3C Proposed Recommendation 27 September 2011

This version:
http://www.w3.org/TR/2011/PR-ws-event-descriptions-20110927
Latest version:
http://www.w3.org/TR/ws-event-descriptions
Previous version:
http://www.w3.org/TR/2011/CR-ws-event-descriptions-20110428
Editors:
Doug Davis, IBM
Ashok Malhotra, Oracle
Katy Warr, IBM
Wu Chou, Avaya

Copyright © 2011 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

This specification describes a mechanism by which an endpoint can advertise the structure and contents of the events it might generate.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

The W3C Membership and other interested parties are invited to review the document and send comments to the Working Group's public mailing list public-ws-resource-access-comments@w3.org mailing list (public archive) until 4 November 2011. See W3C mailing list and archive usage guidelines. Advisory Committee Representatives should consult their WBS questionnaires.

No substantive changes were made as a result of the Candidate Recommendation phase (see also diff, test scenario and implementation report).

A Proposed Recommendation is a specification that is under review by the W3C Advisory Committee for endorsement as a W3C Recommendation. It is is a mature document that has been widely reviewed and has been shown to be implementable. W3C encourages everybody to implement this specification.

Publication as a Proposed Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

It has been produced by the Web Services Resource Access Working Group (WG), which is part of the W3C Web Services Activity.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1 Composable Architecture
2 Introduction
   2.1 Requirements
3 Notations and Terminology
   3.1 Notational Conventions
   3.2 Considerations on the Use of Extensibility Points
   3.3 Terminology
   3.4 Compliance
   3.5 XML Namespaces
4 Advertising Event Information
   4.1 Event Types & Event Descriptions
        4.1.1 Retrieving Event Descriptions
        4.1.2 Bindings for Event Descriptions
5 Acknowledgements
6 References
   6.1 Normative References
   6.2 Informative References

Appendices

A Registration of the application/evd+xml Media Type
B XML Schema for EventDescriptions
C Change Log

1 Composable Architecture

By using the XML and SOAP [SOAP11], [SOAP12] extensibility models, the Web service specifications (WS-*) are designed to be composed with each other to provide a rich set of tools for the Web services environment.

2 Introduction

This specification describes a mechanism by which an endpoint can advertise the structure and contents of the events it might generate.

2.1 Requirements

This specification intends to meet the following requirements:

  • Define a mechanism to describe the structure and contents of events.

  • Leverage WS-MetadataExchange [WS-MetadataExchange] to allow an endpoint to advertise events that might be generated.

3 Notations and Terminology

This section specifies the notations, namespaces, and terminology used in this specification.

3.1 Notational Conventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC 2119].

This specification uses the following syntax to define normative outlines for messages:

  • The syntax appears as an XML instance, but values in italics indicate data types instead of values.

  • Characters are appended to elements and attributes to indicate cardinality:

    • "?" (0 or 1)

    • "*" (0 or more)

    • "+" (1 or more)

  • The character "|" is used to indicate a choice between alternatives.

  • The characters "(" and ")" are used to indicate that contained items are to be treated as a group with respect to cardinality or choice.

  • The characters "[" and "]" are used to call out references and property names.

  • Ellipsis (i.e. "...") indicate a point of extensibility.

  • XML namespace prefixes (see Table 3-1) are used to indicate the namespace of the element being defined.

This specification can be used in terms of XML Information Set (Infoset) [XML Infoset], even though the specification uses XML 1.0 terminology. Valid Infoset for this specification is the one serializable in XML 1.0, hence the use of XML 1.0.

3.2 Considerations on the Use of Extensibility Points

The elements defined in this specification MAY be extended at the points indicated by their outlines and schema. Implementations MAY add child elements and/or attributes at the indicated extension points but MUST NOT contradict the semantics of the parent and/or owner, respectively.

Extension elements and attributes MUST NOT use the Web Services Event Descriptions namespace URI.

3.3 Terminology

Notification

A message sent to indicate that an event, or events, have occurred.

3.4 Compliance

An implementation is not compliant with this specification if it fails to satisfy one or more of the MUST or REQUIRED level requirements defined herein. A SOAP Node MUST NOT use the XML namespace identifier for this specification (listed in 3.5 XML Namespaces) within SOAP Envelopes unless it is compliant with this specification.

Normative text within this specification takes precedence over the XML Schema, which in turn take precedence over outlines, which in turn take precedence over examples.

Unless otherwise noted, all IRIs are absolute IRIs and IRI comparison MUST be performed according to [RFC 3987] section 5.3.1.

Implementations are expected to support both UTF-8 and UTF-16 as described in XML 1.0.

3.5 XML Namespaces

The XML namespace URI that MUST be used by implementations of this specification is: 

http://www.w3.org/2011/03/ws-evd

Table 3-1 lists XML namespaces that are used in this specification. The choice of any namespace prefix is arbitrary and not semantically significant.

Table 3-1: Prefixes and XML namespaces used in this specification
Prefix XML Namespace Specification(s)
s(Either SOAP 1.1 or 1.2)(Either SOAP 1.1 or 1.2)
s11 http://schemas.xmlsoap.org/soap/envelope/ SOAP 1.1 [SOAP11]
s12 http://www.w3.org/2003/05/soap-envelope SOAP 1.2 [SOAP12]
wsa http://www.w3.org/2005/08/addressing WS-Addressing [WS-Addressing]
wsevd http://www.w3.org/2011/03/ws-evd This specification
xs http://www.w3.org/2001/XMLSchema XML Schema [XMLSchema - Part 1], [XMLSchema - Part 2]
wse http://www.w3.org/2011/03/ws-evt WS-Eventing [WS-Eventing]

The working group intends to update the value of the Web Services Event Descriptions namespace URI each time a new version of this document is published until such time that the document reaches Candidate Recommendation status. Once it has reached Candidate Recommendation status, the working group intends to maintain the value of the Web Services Event Descriptions namespace URI that was assigned in the Candidate Recommendation unless significant changes are made that impact the implementation or break post-CR implementations of the specification. Also see http://www.w3.org/2001/tag/doc/namespaceState.html and http://www.w3.org/2005/07/13-nsuri .

4 Advertising Event Information

There are many use cases in which it is necessary for an endpoint to advertise the structure and contents of the events that it might generate. For example, a subscriber might wish to know the shape of the events that are generated in order to properly formulate a filter to limit the number of notifications that are transmitted, or to ensure it can successfully process the type of events that are transmitted.

There are many ways in which an endpoint could describe and advertise the structure of the events for which it will issue notifications. To provide a basic level of interoperability, this specification defines the following mechanism, in 4.1 Event Types & Event Descriptions, for describing and advertising event information.

This specification only defines a mechanism by which events can be described and advertised. How these events, and the properties of these events that are described within an Event Descriptions document, are serialized for transmission is out of scope of this specification; but are expected to be fully described in any specification that uses this one.

4.1 Event Types & Event Descriptions

A key concept in the description and advertisement of event information is the "Event Type". An Event Type is a description of the syntactic structure and value space of the set of events that share that type. Event Types are independent of the pub/sub protocol used and the format of the notifications used to transmit those events.

Event Types are described within an EventDescriptions element where they contain a complete description of an event. A key aspect of this description is the associated XML Schema Global Element Declaration (GED) for each event. EventDescriptions element has the following form: 

<wsevd:EventDescriptions targetNamespace="xs:anyURI" ...>
  <wsevd:types>
    <xs:schema ...>
      ...
    </xs:schema>
    xs:any*
  </wsevd:types>
  <wsevd:eventType id="xs:ID" element="xs:QName"? actionURI="xs:anyURI"? ...>
    xs:any*
  </wsevd:eventType> +
  xs:any*
</wsevd:EventDescriptions>

The XML Schema for the EventDescriptions element can be found in B XML Schema for EventDescriptions. The following describes additional, normative constraints on the outlined listed above:

/wsevd:EventDescriptions

This element contains the declarations of all the Event Types that apply to a given context.

/wsevd:EventDescriptions@targetNamespace

This attribute defines the namespace affiliation of the Event Types declared within the EventDescriptions element. Its value MUST be an absolute IRI [RFC 3987]. It SHOULD be dereferenceable.

/wsevd:EventDescriptions/wsevd:types

This element encloses data type definitions that are relevant to the declared Event Types.

/wsevd:EventDescriptions/wsevd:types/xs:schema

As described earlier, an Event Type is defined by a Global Element Declaration (GED) in XML Schema. This element contains collections of imported and inlined schema components that describe the GEDs that are used to define Event Types.

/wsevd:EventDescriptions/wsevd:eventType

This element describes a specific Event Type.

/wsevd:EventDescriptions/wsevd:eventType/@id

This attribute provides an identifier for this Event Type which MUST be unique amongst all the Event Types defined by the enclosing wsevd:EventDescriptions element. In conjunction with a Prefix that is associated with the value of /wsevd:EventDescriptions/@targetNamespace namespace URI, the value of this attribute MAY be used as the LocalPart of a QName that identifies this Event Type outside the context of the enclosing wsevd:EventDescriptions element.

/wsevd:EventDescriptions/wsevd:eventType/@element

This OPTIONAL attribute refers to a GED defined or imported in the /wsevd:EventDescriptions/wsevd:types element. The referenced GED serves as the definition of this Event Type.

/wsevd:EventDescriptions/wsevd:eventType/@actionURI

This OPTIONAL attribute provides a value for the 'action' property which, depending upon the format of the notification used to transmit the Event, serve as a potential aid to identifying the semantics implied by the message. When not present the implied value of this attribute is the concatenation of the wsevd:EventDescriptions' @targetNamespace attribute and the wsevd:eventType id attribute separated by the '/' character.

Note, while the schema allows for the @element attribute and the @actionURI attribute to be absent, at least one of them MUST be present for each eventType.

The following is an example of an EventDescriptions element that could serve as a description of the Event Type used in Example 4-2.

Example 4-1: EventDescriptions
(01) <wsevd:EventDescriptions 
(02)        targetNamespace="http://www.example.org/oceanwatch/notifications"
(03)        xmlns:wsevd="http://www.w3.org/2011/03/ws-evd"
(04)        xmlns:ow="http://www.example.org/oceanwatch">
(05)   <wsevd:types>
(06)     <xs:schema targetNamespace="http://www.example.org/oceanwatch">
(07)       <xs:include schemaLocation="http://www.example.org/schemas/oceanwatch.xsd"/>
(08)       <xs:element id="WindReport" type="ow:WindReportType"/>
(09)     </xs:schema>
(10)   </wsevd:types>
(11)
(12)   <wsevd:eventType id="WindReportEvent"
(13)                  element="ow:WindReport"
(14)                  actionURI="http://www.example.org/oceanwatch/2003/WindReport"/>
(15) </wsevd:EventDescriptions>

Lines (12-14) describe an Event Type with a QName of "{http://www.example.org/oceanwatch/notifications}:WindReportEvent". The GED for this Event Type is defined on line (08) as being of type "{http://www.example.org/oceanwatch}:WindReportType".

The sample EventDescriptions in Example 4-1 might describe the following notification:

Example 4-2: Hypothetical Notification
(01) <s12:Envelope xmlns:s12="http://www.w3.org/2003/05/soap-envelope"
(02)               xmlns:wsa="http://www.w3.org/2005/08/addressing"
(03)               xmlns:ow="http://www.example.org/oceanwatch">
(04)   <s12:Header>
(05)     <wsa:Action>
(06)       http://www.example.com/oceanwatch/2003/WindReport
(07)     </wsa:Action>
(08)     ...
(09)   </s12:Header>
(10)   <s12:Body>
(11)     <ow:WindReport>
(12)       <ow:Date>030701</ow:Date>
(13)       <ow:Time>0041</ow:Time>
(14)       <ow:Speed>65</ow:Speed>
(15)       <ow:Location>BRADENTON BEACH</ow:Location>
(16)       <ow:County>MANATEE</ow:County>
(17)       <ow:State>FL</ow:State>
(18)       <ow:Lat>27.46</ow:Lat>
(19)       <ow:Long>82.70</ow:Long>
(20)       <ow:Comments xml:lang="en-US" >
(21)         WINDS 55 WITH GUSTS TO 65. ROOF TORN OFF BOAT HOUSE. REPORTED
(22)         BY STORM SPOTTER. (TBW)
(23)       </ow:Comments>
(24)     </ow:WindReport>
(25)   </s12:Body>
(26) </s12:Envelope>

4.1.1 Retrieving Event Descriptions

Although there are many ways in which an endpoint can make its EventDescriptions available, this specification RECOMMENDS the use of the mechanisms described in section 9 of WS-MetadataExchange [WS-MetadataExchange]. In particular, this specification RECOMMENDS that the Event Descriptions metadata be made available through the WS-Eventing [WS-Eventing] EventSource Policy assertion. This MAY be done by either embedding the Event Descriptions metadata directly within the assertion, or by including a MetadataExchange reference to the data.

An event source MUST NOT have more than one EventDescriptions document.

The following examples show how Event Descriptions metadata might appear within a WS-Eventing EventSource Policy assertion.

Example 4-3: Sample Embedded Event Descriptions Metadata
(01) <wse:EventSource ...>
(02)   <wse:FormatName URI="..."/>
(03)   <wsevd:EventDescriptions ...>
(04)     ...
(05)   </wsevd:EventDescriptions>
(06) </wse:EventSource>

Example 4-3 shows how the Event Descriptions metadata might be embedded directly within a WS-Eventing EventSource Policy assertion.

Example 4-4: Sample Reference to Event Descriptions Metadata
(01) <wse:EventSource ...>
(02)   <wse:FormatName URI="..."/>
(03)   <mex:Location 
(04)     Type="wsevd:EventDescriptions"
(05)     URI="http://example.com/EVD_Metadata" />
(06) </wse:EventSource>

Example 4-4 shows the same policy assertion from Example 4-3 except the embedded Event Descriptions metadata is replaced with a reference to an HTTP resource whose representation is the Event Descriptions metadata. The data can be retrieved via an HTTP GET to the specified URL.

Example 4-5: Sample GetMetadataResponse with Event Descriptions Metadata
(01) <mex:GetMetadataResponse>
(02)   <mex:Metadata>
(03)     <mex:MetadataSection Dialect='wsevd:EventDescriptions'
(04)         Identifier='...'>
(05)       <wsevd:EventDescriptions ...>
(06)         ...
(07)       </wsevd:EventDescriptions>
(08)     </mex:MetadataSection>
(09)   </mex:Metadata>
(10) </mex:GetMetadataResponse>

Example 4-5 shows how the Event Descriptions metadata might appear within a GetMetadataResponse message.

If an EventDescriptions document appears within a WS-MetadataExchange MetadataSection, then the value of the @Identifier attribute, if present, MUST be equal to the value of its wsevd:EventDescription/@targetNamespace.

4.1.2 Bindings for Event Descriptions

Any specification of a publish-subscribe system that uses Event Descriptions to advertise the events that are generated MUST clearly define how those events are serialized when they are transmitted to the receiver of notification messages.

5 Acknowledgements

This specification has been developed as a result of joint work with many individuals and teams, including: Alessio Soldano (Red Hat), Ashok Malhotra (Oracle Corp.), Asir Vedamuthu (Microsoft Corp.), Bob Freund (Hitachi, Ltd.), Bob Natale (MITRE Corp.), David Snelling (Fujitsu, Ltd.), Doug Davis (IBM), Fred Maciel (Hitachi, Ltd.), Geoff Bullen (Microsoft Corp.), Gilbert Pilz (Oracle Corp.), Greg Carpenter (Microsoft Corp.), Jeff Mischkinsky (Oracle Corp.), Katy Warr (IBM), Li Li (Avaya Communications), Mark Little (Red Hat), Martin Chapman (Oracle Corp.), Paul Fremantle (WSO2), Paul Nolan (IBM), Prasad Yendluri (Software AG), Ram Jeyaraman (Microsoft Corp.), Sreedhara Narayanaswamy (CA), Sumeet Vij (Software AG), Tom Rutt (Fujitsu, Ltd.), Vikas Varma (Software AG), Wu Chou (Avaya Communications), Yves Lafon (W3C/ERCIM).

6 References

6.1 Normative References

RFC 2119
Key words for use in RFCs to Indicate Requirement Levels , S. Bradner, Author. Internet Engineering Task Force, March 1997. Available at http://www.ietf.org/rfc/rfc2119.txt.
RFC 3023
XML Media Types , M. Murata, S. St. Laurent, D. Kohn, Authors. Internet Engineering Task Force, January 2001. Available at http://www.ietf.org/rfc/rfc3023.txt.
RFC 3987
Internationalized Resource Identifiers (IRIs) , M. Duerst and M. Suignard, Authors. Internet Engineering Task Force, January 2005. Available at http://www.ietf.org/rfc/rfc3987.txt.

6.2 Informative References

SOAP11
W3C Note, "Simple Object Access Protocol (SOAP) 1.1" , D. Box, et al, Editors. World Wide Web Consortium (W3C), 8 May 2000. Available at http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.
SOAP12
W3C Recommendation, "SOAP Version 1.2 Part 1: Messaging Framework" , M. Gudgin, M. Hadley, N. Mendelsohn, J-J. Moreau, H. Frystyk Nielson, Editors. World Wide Web Consortium (W3C), 27 April 2007. Available at http://www.w3.org/TR/soap12-part1/.
WS-Addressing
W3C Recommendation, "Web Services Addressing 1.0 (WS-Addressing)" , M. Gudgin, M. Hadley, T. Rogers, Editors. World Wide Web Consortium (W3C), 9 May 2006. Available at http://www.w3.org/TR/ws-addr-core.
WS-Eventing
W3C Working Group Draft, "Web Services Eventing (WS-Eventing) 1.1" , D. Davis, et al., Editors. World Wide Web Consortium (W3C), 15 September 2009. Available at http://www.w3.org/TR/ws-eventing.
WS-MetadataExchange
W3C Working Group Draft, "Web Services Metadata Exchange (WS-MetadataExchange) 1.1" , D. Davis, et al., Editors. World Wide Web Consortium (W3C), 15 September 2009. Available at http://www.w3.org/TR/ws-metadata-exchange.
xml:id
W3C Recommendation, "xml:id Version 1.0" , J. Marsh, et al., Editors. World Wide Web Consortium (W3C), 9 September 2005. Available at http://www.w3.org/TR/xml-id/.
XML Infoset
W3C Recommendation, "XML Information Set (Second Edition)" , J. Cowan, R. Tobin, Editors. World Wide Web Consortium (W3C), 4 February 2004. Available at http://www.w3.org/TR/xml-infoset.
XMLSchema - Part 1
W3C Recommendation, "XML Schema Part 1: Structures (Second Edition)" , H. Thompson, et al., Editors. World Wide Web Consortium (W3C), 28 October 2004. Available at http://www.w3.org/TR/xmlschema-1/.
XMLSchema - Part 2
W3C Recommendation, "XML Schema Part 2: Datatypes (Second Edition)" , P. Biron, A. Malhotra, Editors. World Wide Web Consortium (W3C), 28 October 2004. Available at http://www.w3.org/TR/xmlschema-2/.

A Registration of the application/evd+xml Media Type

This appendix defines the 'application/evd+xml' media type which can be used to describe EventDescription documents serialized as XML.

Type name:

application

Subtype name:

evd+xml

Required parameters:

none

Optional parameters:

charset
This parameter has identical semantics to the charset parameter of the 'application/xml' media type as specified in [RFC 3023].

Encoding considerations:

Identical to those of 'application/xml' as described in [RFC 3023], section 3.2, as applied to the EventDescriptions document.

Security considerations:

Same as that of Section 10 in [RFC 3023].

Interoperability considerations:

There are no known interoperability issues.

Published specification:

Web Services Event Descriptions (this specification).

Applications which use this media type:

No known applications currently use this media type.

Additional Information:

Magic number(s):
None.

File extension(s):
evd

Fragment identifiers:
An EventDescriptions fragment identifier references a particular Event Type within an EventDescriptions document. The Event Type referenced is the Event Type with the @id attribute whose normalized value (per [xml:id]) equals that of the fragment identifier component.

For example, if the EventDescriptions document from Example 4-1 were located at "http://www.example.com/eventtypes/oceanwatch", the following URI references the Event Type defined in lines 12-14: http://www.example.com/eventtypes/oceanwatch#WindReportEvent.

Macintosh file type code(s):
No Macintosh file type code defined.

Person and email address to contact for further information:

World Wide Wed Consortium <web-human@w3.org>

Intended usage:

COMMON

Restrictions on usage:

none.

Author/Change controller:

The WS-EventDescriptions specification is a work product of the World Wide Web Consortium's Web Service Resource Access Working Group. The W3C has change control over these specifications.

B XML Schema for EventDescriptions

A normative copy of the XML Schema [XMLSchema - Part 1], [XMLSchema - Part 2] description for the EventDescriptions element can be retrieved from the following address: 

http://www.w3.org/2011/03/ws-evd/eventdescriptions.xsd

A non-normative copy of the XML schema is listed below for convenience. 

<xs:schema xmlns:xs='http://www.w3.org/2001/XMLSchema'
           targetNamespace='http://www.w3.org/2011/03/ws-evd'
           elementFormDefault='qualified' attributeFormDefault='unqualified'>
  <xs:element name='EventDescriptions'>
    <xs:complexType>
      <xs:sequence>
        <xs:element name='types'>
          <xs:annotation>
            <xs:documentation>Data type definitions that are relevant to described notifications.</xs:documentation>
          </xs:annotation>
          <xs:complexType>
            <xs:sequence>
              <xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
            </xs:sequence>
            <xs:anyAttribute namespace='##other' processContents='lax'/>
          </xs:complexType>
        </xs:element>
        <xs:element name='eventType' maxOccurs='unbounded'>
          <xs:complexType>
            <xs:sequence>
              <xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
            </xs:sequence>
            <xs:attribute name='id' type='xs:ID' use='required'/>
            <xs:attribute name='element' type='xs:QName' use='optional'/>
            <xs:attribute name='actionURI' type='xs:anyURI' use='optional'/>
            <xs:anyAttribute namespace='##other' processContents='lax'/>
          </xs:complexType>
        </xs:element>
        <xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:attribute name='targetNamespace' type='xs:anyURI' use='required'/>
      <xs:anyAttribute namespace='##other' processContents='lax'/>
    </xs:complexType>
  </xs:element>
</xs:schema>

C Change Log

Data Author Description
2010/01/19 DD Added resolution of issue 8068
2010/03/09 DD Added resolution of issue 6463, 8031, 8198
2010/03/16 DD Added resolution of issue 8900
2010/03/30 DD Added resolution of issue 9031
2010/04/20 DD Added resolution of issue 9321
2010/05/04 DD Added resolution of issue 9087
2010/08/18 DD Added resolution of issue 10376
2011/01/04 DD Added resolution of issue 11551
2011/07/12 DD Added resolution of issue 13227