Remote Events for XML (REX) 1.0 is an XML [XML] grammar for representing events as they are defined in DOM 3 Events [DOM3EV], primarily but not exclusively for purposes of transmission. It enables one endpoint to interact remotely with another endpoint holding a DOM representation by sending it DOM Events as if they had occurred directly at the same location.
This document is a Working Draft produced by a joint task force of the SVG WG (part of the Graphics Activity) and the Web API WG (part of the Rich Web Clients Activity). Please send comments to public-webapi@w3.org (Archive), the public email list for issues related to Web APIs.
The patent policy for this document is the 5 February 2004 W3C Patent Policy. W3C maintains the SVG Working Group's public list of patent disclosures and the Web API Working Group's public list of patent disclosures made in connection with the deliverables of these groups; 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.
The Remote Events for XML (REX) specification defines a transport agnostic XML syntax for the transmission of DOM events as specified in the DOM 3 Events specification [DOM3EV] in such a way as to be compatible with streaming protocols. REX assumes that the transport provides for reliable, timely and in sequence delivery of REX messages. REX does not cover the process of session initiation and termination which are presumed to be handled by other means.
The first version of this specification deliberately restricts itself to the transmission of mutation events (events which notify of changes to the structure or content of the document) so as to remain limited in scope and allow for progressive enhancements to implementations over time rather than require a large specification to be deployed at once. The framework specified here is however compatible with the transmission of any other event type, and great care has been taken to ensure its extensibility and evolvability.
A variety of usage situations in for which REX can be used are exemplified below, also showing some specific features available when using REX.
The following REX message sets the fetch attribute to "ball"
on an element that has an ID of spot.
Note that we do not specify the
The following REX message adds a row at the seventh position (that is, after the current sixth and before the current seventh, which becomes the eighth) in the second table contained in the document's body.
The following REX message removes the first circle
that is a child of the element with id poodle-stylist-location-layer.
Note that while the target path may match multiple elements, REX limits the list to the first one that matches. Future versions may include a flag to target multiple elements.
The following REX message replaces an element with ID femur
with the new one provided in the payload.
Replacement is expressed as a removal with a payload. The processing model is exactly the same as if an event had been transmitted indicating removal, followed by another indicating insertion (internally, a REX user-agent processes both in the exact same manner — which also matches the manner in which a DOM implementation would perform this task) but this shorthand simplifies content generation and is more efficient both in bandwidth and in processing time (since the target only needs to be resolved once).
The following REX message replaces an entire SVG document with a new one.
Again, XPath's simple modelling of a document hierarchy is used to
address the node we want to replace, in this case the document node
captured simply as "/".
All nodes, including text, can be updated directly. However character
data has specific events in the DOM that are more straightforward and
can be more lightweight to use. REX supports encapsulating such
updates as well. The following example updates the seventh tspan
element's textual data with new text.
The namespace for the REX language is: http://www.w3.org/ns/rex#.
Future versions of this specification will use the same namespace, unless the language is changed in such radical ways that an implementation of previous versions would not be able to process it in a meaningful manner. Implementations of this specification therefore MUST be able to process extensions to the syntax defined in this version, as detailed in the Extensibility section.
All REX messages MUST be contained within a
The
1.0, 1, or 1.00 are all different versions.
A user-agent supporting this version of the specification MUST accept version identifier
1.0. If the version number is not in the list of versions of this specification
supported by the user-agent, the user-agent MUST reject the message completely and
immediately, ignoring the entirety of its content.
The
The
If the
The
Target nodes are referenced using a subset of XPath [XPATH] that corresponds to the level of expressivity that meets most needs while at the same time remaining easy to implement. There is never a need to resolve a relative path as they are always anchored either at the root (absolute paths) or at an element ID.
Target paths MUST be processed as follows, even if internal details of implementation differ. The result of evaluating the target path against the target document is a node-set, ordered according to the axes used in the target path, as per XPath. Note however that the limited set of axes available in this subset will always cause the node-set to be in document order unless a superset of the minimal syntax is used.
If the size of the node-set is superior to one, only the first item in that node-set MUST be considered for processing, and the rest MUST be discarded.
If the size of the node-set is zero, the event MUST be ignored and thus nothing happens.
The set of namespace declarations made available to the target path are those in scope
on the element on which the target path occurs; this includes the implicit declaration
of the prefix xml required by Namespaces in XML [XMLNS]; the default namespace
(as declared by xmlns) is not part of this set.
The syntax for target paths is a very simple subset of XPath described by the following
syntax, in which the Name token is taken from the XML specification [XML]
and the NCName token is from the Namespaces in XML specification [XMLNS].
User-agents MAY support a superset of this syntax so long as it is a valid instance of the XPath language [XPATH]. Content producers however SHOULD NOT use such extensions as they hamper interoperability.
The subset of XPath normatively defined in the above grammar can be summarised by a
few general ideas. Target paths may only begin at the root or with an id()
function. The id() function itself is limited to a single string argument,
which in turn must contain exactly one identifier (as opposed to a white space separated
list in XPath). Only abbreviated axes are supported in the syntax. Following the
beginning of the path may be a list of steps, making use only of the child
axis, and only element name tests. The final step in the list is more
powerful and may also reference text nodes. For each step a predicate may
be used, which is limited to only containing an integer indicating position.
Some examples of target paths include:
/svg:svg will match the root svg element, in the namespace
that has been bound to the 'svg' prefix.
/lodges/donkey[8] will match the eighth donkey element in the
lodges element with no namespace.
/ will match the root node, which is to say the document itself.
/foo/text() will match the first text node that is a child of the
the foo element.
/xhtml:html/xhtml:body/svg:svg[3] will match the third svg
element that is a child of the root body and then html
elements.
id("dahut") will match the element with ID 'dahut'.
id("dahut")/svg:circle will match the first circle element
that is a child of the element with ID 'dahut'.
Note that it is possible using this syntax to produce target paths that will never match
anything (for instance /element[2]). Such constructions simply cause the
event to be ignored.
This section defines how REX messages are processed by user-agents. Its intent is not to prescribe implementation details — the processing MAY be implemented in ways that differ from the steps described below, but if so the effect MUST be exactly equivalent.
It is RECOMMENDED that REX messages be processed in a streaming fashion, so that the user-agent is not required to build a tree representation of the message. This is of particular importance in that a single REX message MAY capture a very long list of individual events over a long period of time, which would cause the resulting tree to consume potentially large amounts of memory.
Events that do not have a time stamp MUST be dispatched in the same order in which they occur in the REX message. If the user-agent supports the Streaming Module then events that have a time stamp MAY be caused to be processed in an order different from the one in which they occur in the REX message, as described below.
Because user-agents are encouraged to process events that do not have a time stamp as soon as
possible, a REX message containing a well-formedness error SHOULD still cause previous
As soon as an
Event object (as defined in DOM 3 Events [DOM3EV]) MUST be created as defined
in the Mapping event elements to Event objects
section below. Note that in some cases, multiple Event objects may be created
by a single
As soon as an
There is no requirement on the user-agent to support a DOM interface in order to still implement events received through REX messages. For instance, specifications such as SMIL [SMIL2] or XML Events [XMLEV] may be handling events received through REX messages in the absence of a DOM representation of the document tree.
Note that given the presence of time stamps, it is possible for content to require of the user-agent that it queue up a potentially unlimited number of events, which may lead to exhausting available memory. In order to avoid this, servers SHOULD arrange to deliver events in a sequence that minimises memory requirements for user-agents. Also, user-agents MAY process events earlier than indicated if not doing so would result in exhausting memory resources. If doing so, then user-agents MUST process these events in the order in which the timing would have required that they process them.
In processing
When the event type is recognised by the processor, it needs to create an object of the appropriate subclass of Event. The precise details of doing so are defined in the sections that handle mappings of specific event types. In this specification there is only one such section, Encoding Mutation Events.
The are two types of unknown events:
mousemove
event on a device that has no pointer device cursor).
When encountering an unknown even, a user-agent MUST ignore the entire
Note that we could make this extensible, but it would require adding a bunch of attributes (bubbles, cancellable, etc.) so that unknown events could be processed. This should be done in the next version.
There is almost always a mismatch between the information that an XML document is able to capture and the information that an in-memory representation of the same document is able to expose. In some cases, this mismatch is strong enough that some major XML constructs such as processing instructions or comments cannot be represented. This section defines how a user-agent is to handle node types that it is unable to produce a representation of.
It should be noted that there is no requirement that a node type captured in a REX message have a corresponding object or interface in the DOM variant used by the user-agent. For instance, the SVG 1.2 MicroDOM [SVGT12] has no interface to represent text nodes but it is nevertheless able to store text content and even mixed content. Therefore a user-agent using the MicroDOM will be able to process text nodes that it receives from REX messages.
The are two situations in which unsupported node types may be encountered:
If the target path requires support for a node type that is not supported by the
implementation, then the user-agent MUST ignore the entire
If the payload of the textContent interface. If removing these nodes
from the payload causes the payload to become empty, then the entire
In order for REX to be extensible, it is necessary to define a strict extensibility model that allows future versions to introduce new constructs into messages that will still be understood to the best of their abilities by older user-agents.
A REX message that is intended to be understood if and only if the user-agent supports
a minimal version of the REX specification MUST set the
There are three categories of unknown elements:
Outside of
Inside
There are two types of unknown attributes that MAY occur on REX elements:
When encountering an unknown attribute, a user-agent MUST process the corresponding element as if the attribute had not been specified at all.
Likewise, if a known attribute with an invalid value is encountered, it MUST be ignored as if it had not been specified.
Some of the events that can be captured in REX messages will cause the DOM tree that they target to be modified. In addition to the specific error handling specified in the respective event definitions, the following rules apply:
For every part of this specification for which a given event or element is said to be ignored, a user-agent MUST skip it as if it had not at all occurred within the REX message (and if the entire REX message is ignored, as if it had never been received at all). The user SHOULD NOT be informed of such occurrences.
However if instead of a user-agent the REX processor is a content checker, then each given occurrence of an item that is said to be ignored MUST be considered to be an error. Such errors MUST be reported to the user of the content checker. More information is available on classes of REX processors in the Conformance section.
This chapter of the specification contains aspects of REX that are only useful within streaming environments in which features such as timing, synchronisation, or tune-in are relevant. As such, it is optional for implementations not intended to operate in such environments, and constitutes a separate conformance level.
The reference event is an event, of any type, that is defined to serve
as the reference point for time stamps on events following this one.
Any anchor becomes a reference event. All
events that follow it in the stream and have a time stamp have that time
stamp defined as an offset from when the reference event became active.
If an anchor, then the
When no reference event has yet been seen, the time from which time stamps are offset defaults to the beginning of the session.
The anchor and implicit.
When set to anchor, the corresponding event MUST be used as
a reference event, as defined above. When set to implicit
the behaviour of the implicit.
The
In continuous streaming and broadcast scenarios it is important that a user-agent be able to tune into a stream at an arbitrary moment and nevertheless be able to start using it as early as possible. This requires three distinct but related pieces of functionality:
The above functionality is obtained through the use of two attributes on the
This functionality can be used as follows. A message containing enough of the
document for tune-in would be transmitted with a
The above can be processed immediately, whether or not the user-agent has received previous messages in the stream or not. The following one on the other hand is a message that is only relevant if the user-agent has already received the previous message. If it hasn't, then it will ignore it.
Therefore, in a broadcast or multicast environment one may see sequences of events similar to the following:
In the above, if a user-agent starts receiving the stream of REX messages from
the first seq=3, it will ignore all the following ones until it
receives seq=4 which provides it with sufficient context to
display something.
All mutations events
are in no namespace. Only the following events are
supported by this specification:
Mutation events are specific in REX processing in that they cause the DOM tree to be modified. When a user-agent processes a mutation event received in a REX message, in addition to dispatching the event it MUST also modify the tree (either before or after the event, as specified depending on the event type) according to the event type.
In processing an
The DOMSubtreeModified is not supported. Implementations SHOULD process it as an unknown event.
The DOMNodeInserted indicates that a node has been inserted into the DOM tree. The inserted node MUST be either of an element, a text node, a comment, or a processing instruction. The target path is used to specify the parent of the node that is to be inserted, and MUST point either to an element or to the document root. If the element that it points to does not exist then the event MUST be ignored.
If there is more than one child node in the payload, they MUST be inserted one after
the other in document order, as if a DOM DocumentFragment were being inserted. Each of
them in turn MUST produce a
DOMNodeInserted
event as if they had been transmitted in separate
Note that as specified in DOM 3 Events [DOM3EV] this event MUST be dispatched after the node has been inserted.
When this event is transmitted, the
parent.childNodes.item(position)
would return the first node of the payload. If position is not specified, or if the specified
value is higher than the number of item or lower than zero then the nodes MUST be inserted
at the end of the list of child nodes.
Please note that the payload of
And given the following
Will produce the following result:
And not what some may have expected:
In order to obtain the above, the white space before and after "Poodles are for maniacs!" would have had to be removed.
The DOMNodeRemoved event indicates that a node has been removed from the DOM tree. The target path MUST point to either an element, a text node, a comment, or a processing instruction. If it points to an attribute the event MUST be ignored. If the node pointed to by the target path does not exist, then the event MUST be ignored.
If the
The following parameters MUST be set for the generated event. It is of type
/') in which case the generated event
also points to the root node. Its
Note that the above processing is compatible with that of DOM 3 Core [DOM3] Node.replaceChild() but more powerful since it can also operate on the document itself.
Note that as specified in DOM 3 Events [DOM3EV] this event MUST be dispatched before the node is removed.
The event adds no attribute to the
The DOMNodeRemovedFromDocument is not supported. Implementations SHOULD process it as an unknown event. It is nevertheless dispatched after a DOMNodeRemoved event as described in DOM 3 Events [DOM3EV].
The DOMNodeInsertedIntoDocument is not supported. Implementations SHOULD process it as an unknown event. It is nevertheless dispatched after a DOMNodeInserted event as described in DOM 3 Events [DOM3EV].
The DOMAttrModified event indicates that an attribute has been modified, added, or removed.
When representing a
If the removal
then the attribute pointed to by the target path and modification or addition then there are two possible options:
modification;
addition;
Note that as specified in DOM 3 Events [DOM3EV] this event MUST be dispatched after the node has been modified.
The following attributes are added to the
null.
If it does have a prefix, then its namespace URI component MUST be that corresponding
to that prefix in the namespace declarations in scope for the xml
required by Namespaces in XML [XMLNS] and exclusive of the default namespace. If the
QName is not namespace well-formed [XMLNS] either because the prefix cannot be resolved
to a namespace declaration in the current scope, or because it is syntactically
invalid, then the entire event MUST be ignored. This attribute is required.
modification,
addition, or removal. The default value is modification.
Note that the distinction between addition and modification is
largely for documentation purposes as the user-agent changes one into the other depending
on the presence or not of the attribute.
modification, then the addition.
addition, then the modification.
removal, then the target attribute MUST be removed. If the
target attribute is not present, then the event MUST be ignored. If
The DOMCharacterDataModified
event indicates that character data has been modified, where that character data can be either a text node,
a comment node, or the data of a processing instruction node. When representing a
Note that as specified in DOM 3 Events [DOM3EV] this event MUST be dispatched after the node has been modified.
Neither of the mutation name events (DOMElementNameChanged and DOMAttributeNameChanged) is supported. Implementation SHOULD process them as unknown events.
The key words "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 [RFC2119].
Unless otherwise specified immediately following the header, all sections in this document — to the exclusion of examples which are all informative — are normative.
The parsing of attribute values MUST be performed as follows:
Things currently missing from this section:
GP1. Classes of products: content, content producers, user-agents. For UAs, two levels: one with a DOM (indicate variations) and one without.
GP3. Not sure exactly how to best do this. Could be useful, need to ask for input.
GP4. Do this as soon as test are being written.
GP5. Delayed until GP3 & GP4 are done.
GP7. Not sure if this is examples or if it's test suite. If former done, if latter starting right after FPWD.
Req3. See GP1.
GP8. Once the text is a little bit more stable, go through the list of bibrefs and check to see which ones are good.
Req5. Implement proper <dfn> support, and based on that do exactly this.
Req6. Do this as part of GP1.
GP9. Do this with Req5.
GP10. Left for later check (at FPWD time I would expect).
GP12. Testable assertions will need further checking. Do this as part of the post FPWD work on testing.
GP19. Add some text in the section on extensibility to make sure implementers understand how not to get extensibility wrong.
This table is derived from the checklist of all defined requirements and good practices from the QA Framework: Specification Guidelines [QAF-SPEC]. For each requirement and good practice, the table links to the part of the REX specification that satisfies the requirement or best practice, except where the entry corresponds to many parts of the specification, or even the specification as a whole.
There are two features for which optionality is to be found:
The editor would like to thank Dave Raggett for his excellent input and comments. This specification is a collective work that derives from other solutions in the domain. Notable amongst its initial influences are an input document from Nokia the ideas from which were incorporated into this specification, XUpdate which has been a major de facto solution since the year 2000 and was influential in REX's technical design, and the XUP W3C Member Submission (now OpenXUP) from which much inspiration was drawn.
The IETF WiDeX Working Group has been a pleasure to collaborate with and has provided a substantial amount of input, much of which has made its way directly into this specification. Many thanks are also due to the MWI and XML Core WGs for their excellent comments and suggestions. Takanari Hayama designed the tune-in part of the specification.
Many thanks to Karl Dubost and the QA WG for their very helpful review.
The following individuals, in no particular order, have provided valuable comments that have helped shape REX: Ola Andersson, Stéphane Bortzmeyer, Gerd Castan, John Cowan, Elliotte Rusty Harold, Takanari Hayama, Ian Hickson, Björn Hörhmann, Philippe Le Hégaret, Paul Libbrecht, Chris Lilley, Cameron McCormack, David Rivron, Elin Röös, Dave Singer, Maciej Stachowiak, Ruud Steltenpool, and Jin Yu.
This appendix registers a new MIME media type, "application/rex+xml"
in conformance with
RegMedia and
W3CRegMedia.
None
The encoding of a REX document MUST be determined by the XML encoding declaration. This has identical semantics to the application/xml media type in the case where the charset parameter is omitted, as specified in RFC 3023 [RFC3023] sections 8.9, 8.10 and 8.11.
As with other XML types and as noted in RFC 3023 [RFC3023] section 10, repeated expansion of maliciously constructed XML entities can be used to consume large amounts of memory, which may cause XML processors in some environments to fail.
REX documents may be transmitted in compressed form using gzip compression. For systems which employ MIME-like mechanisms, such as HTTP, this is indicated by the Content-Encoding header; for systems which do not, such as direct file system access, this is indicated by the file name extension or file metadata. In addition, gzip compressed content is readily recognised by the initial byte sequence as described in RFC 1952 [RFC1952] section 2.3.1.
It must be noted that REX events MAY be used to modify the document that they target, and in fact that is the primary functionality that they expose in version 1.0. Such modifications may cause security issues with the processor of the target document, but those issues are outside the scope of this registration document.
In addition, because of the extensibility features for REX and of XML in
general, it is possible that "application/rex+xml" may describe
content that has security implications beyond those described here. However,
if the processor follows only the normative semantics of this specification,
this content will be outside the REX namespace and MUST be ignored. Only in
the case where the processor recognises and processes the additional content,
or where further processing of that content is dispatched to other processors,
would security issues potentially arise. And in that case, they would fall
outside the domain of this registration document.
This specification describes processing semantics that dictate behaviour that must be followed when dealing with, among other things, unrecognised elements, events, and attributes, both in the REX and XML Events namespaces and in other namespaces.
Because REX is extensible, conformant "application/rex+xml"
processors MUST expect that content received is well-formed XML, but it
cannot be guaranteed that the content is valid to a particular grammar,
or that the processor will recognise all of the elements and attributes
in the document — in fact it will likely not recognise the payload. Rules
are defined so that such extended documents are guaranteed to be processed
in an interoperable manner.
REX has a published Test Suite and associated implementation report showing which implementations passed which tests at the time of the report. This information is periodically updated as new tests are added or as implementations improve.
This media type registration is extracted from Appendix A of the REX 1.0 specification.
This sections lists the changes that were made to this specification since it was last published. Many thanks too all those who have provided feedback.
namespaceURI is defined to be
its URI equivalent (John Cowan).