Remote Events for XML (REX) 1.0

1.1. Examples of usage

A variety of usage situations in for which REX can be used are exemplified below, also showing some specific features available when using REX.

<rex xmlns='https://www.w3.org/ns/rex#'>
  <event target='id("spot")' attrName='fetch' name='DOMAttrModified' newValue='ball'/>
</rex>

<rex xmlns='https://www.w3.org/ns/rex#' xmlns:x='https://www.w3.org/1999/xhtml'>
  <event target='/x:html/x:body/x:table[2]' name='DOMNodeInserted' position='7'>
    <tr xmlns='https://www.w3.org/1999/xhtml'>
      <td>Rover</td>
      <td>Alpine Labrador</td>
      <td class='food'>bone</td>
    </tr>
  </event>
</rex>

<rex xmlns='https://www.w3.org/ns/rex#' xmlns:svg='https://www.w3.org/2000/svg'>
  <event target='id("poodle-stylist-location-layer")/svg:circle' name='DOMNodeRemoved'/>
</rex>

<rex xmlns='https://www.w3.org/ns/rex#'>
  <event target='id("femur")' name='DOMNodeRemoved'>
    <bone xmlns='https://example.org/BoneML' xml:id='tibia'>
      <taste>good</taste>
      <smell>excellent</smell>
      <solidity>medium</solidity>
      <availability>common</availability>
    </bone>
  </event>
</rex>

<rex xmlns='https://www.w3.org/ns/rex#'>
  <event target='/' name='DOMNodeRemoved'>
    <svg xmlns='https://www.w3.org/2000/svg' viewBox='0 0 300 400'>
      <defs>
        <!-- ... --->
      </defs>
      <g>
        <rect x='42' y='27' width='100' height='200' fill='orange'/>
        <!-- ... --->
      </g>
    </svg>
  </event>
</rex>

<rex xmlns='https://www.w3.org/ns/rex#' xmlns:svg='https://www.w3.org/2000/svg'>
  <event target='/svg:svg/svg:g[2]/svg:tspan[7]/text()' name='DOMCharacterDataModified' newValue='Hello World!'/>
</rex>

2.1. The <rex> element

The <rex> element serves as the root container for the entire REX message. It MUST be present, even if there is only one <event> element. Elements in the REX namespace that do not have a <rex> ancestor MUST be ignored by the user-agent.

<define name='rex'>
  <element name='rex'>
    <optional>
      <attribute name='minimal-version'>
        <value>1.0</value>
      </attribute>
    </optional>
    <optional>
      <attribute name='target-document'>
        <text/>
      </attribute>
    </optional>
    <ref name='ns'/>
    <ref name='rex.AT'/>
    <oneOrMore>
      <ref name='event'/>
    </oneOrMore>
  </element>
</define>

Attributes list

minimal-version

Indicates the minimum version of the REX specification required to usefully process this message. While the version value has the form of a float it is actually processed as a string and user-agents MUST therefore compare the provided 'minimal-version' against the strings of all versions that they know and MUST NOT perform numeric comparisons. This entails that 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.

target-document

In some cases a user-agent may have multiple document in memory, or even inside the current view. The 'target-document' attribute is used to identify which document is being addressed by this given REX message. Its content is an opaque string, and the manner in which the user-agent maps such identifiers to the documents that it contains as well as the absence of a 'target-document' identifier to a "default" or "active" document is left for the target environments to define. An empty 'target-document' MUST be processed as if the attribute had not been specified. If a user-agent receives a REX message with a 'target-document' that it cannot map onto a document then the entire REX message MUST be ignored.

Other attributes

See 'ns' .

The <rex> element MUST contain one or more <event> elements. Otherwise, the message is invalid and the user-agent MUST ignore it entirely.

<rex xmlns='https://www.w3.org/ns/rex#'
     xmlns:svg='https://www.w3.org/2000/svg'>
  <event target='id("shiny-donkey")' name='DOMNodeRemoved'/>
  <event target='/svg:svg/svg:g[5]/svg:a[2]' name='activate'/>
  <event target='/svg:svg/svg:g[7]' name='DOMNodeInserted' position='9'>
    <svg:rect x='9' y='42' width='432' height='217' fill='red'/>
  </event>
  <event target='id("dahut")' name='DOMNodeRemoved'>
    <svg:circle cx='19' cy='17' r='42' fill='orange'/>
  </event>
</rex>

2.2. The 'ns' attribute

The 'ns' attribute defines the namespace that applies to DOM event names within the scope of the element on which it occurs. For any given DOM event name, if there is no 'ns' attribute on any of its ancestor elements, that event name's URI component is the empty string. Otherwise, it will have the namespace component corresponding to the first 'ns' attribute found on its ancestor elements in reverse document order. The content of the 'ns' attribute is either an IRI or the empty string. If the empty string then event names in its applicable scope will have no namespace URI component.

If the 'ns' attribute contains a non-empty string, then it SHOULD be a valid IRI. However, given the complexity involved in checking IRI validity it is not RECOMMENDED that user-agents validate them. If however IRI validation is performed and the IRI value of the 'ns' attribute is found to be false, then the entire subtree inclusive of the element on which the 'ns' attribute occurs MUST be ignored.

<define name='ns'>
  <optional>
    <attribute name='ns'>
      <choice>
        <data type='anyURI'/>
        <empty/>
      </choice>
    </attribute>
  </optional>
</define>

2.3. The <event> element

The <event> element is used to encode any kind of event that may be captured in REX. While the 'name' and 'target' attributes MUST always be specified, the rest of its content model depends on the event that it captures. Each <event> element MUST produce at least one corresponding DOM event (and on some occasions a modification of the DOM tree) unless it is ignored according to a part of this specification.

<define name='event'>
  <element name='event'>
    <ref name='ns'/>
    <attribute name='target'>
      <text/>
    </attribute>
    <attribute name='name'>
      <data type='NMTOKEN'/>
    </attribute>
    <ref name='timeStamp.AT'/>
    <ref name='timeRef.AT'/>
    <choice>
      <ref name='DOMNodeInserted'/>
      <ref name='DOMNodeRemoved'/>
      <ref name='DOMAttrModified'/>
      <ref name='DOMCharacterDataModified'/>
    </choice>
  </element>
</define>

Attributes list

name

Contains the local name component of the name of the event represented by this <event> element. The namespace URI component of the event's name MUST be resolved based on the 'ns' attribute.

target

The 'target' attribute contains the target path as described in the Referencing target nodes section.

Other attributes

See 'ns' .

3.1. Processing target paths

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.

3.2. Path syntax

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].

FullPath  ::= RPath | Root | IDPath
SubPath   ::= Step* FullTest
RPath     ::= '/' SubPath
Root      ::= '/'
IDPath    ::= 'id(' NCNameStr ')' RPath?
Step      ::= StepTest '/'
StepTest  ::= Name ('[' Num ']')?
FullTest  ::= (Name | 'text()') ('[' Num ']')?
NCNameStr ::= "'" NCName "'" | '"' NCName '"'
Num       ::= [0-9]+

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.

4.1. Mapping <event> elements to Event objects

In processing <event> elements and converting them into Event objects, the user-agent MUST inform the various fields of the object in the following manner:

type

Set to the 'name' attribute of the <event> element.

namespaceURI

Set to URI equivalent of the value of the 'ns' attribute, resolved as described in its own section.

target

Set dynamically to be in turn each node in the node-set obtained by resolving the target path.

currentTarget

Set dynamically as the event is being processed, as described in the DOM event flow.

eventPhase

Set dynamically depending on whether the event is currently progressing through the capture, target, or bubble phase. Note that this specification does not require that given phases be supported by the implementation, this is left to the specifications with which it is used in conjunction to define.

bubbles

Specifies whether an event is one that bubbles or not. The implementation sets that using its knowledge of the given event type.

cancelable

Specifies whether an event can have its default action prevented or not. The implementation sets that using its knowledge of the given event type.

timeStamp

If the implementation supports the 'timeStamp' attribute and it has been set, this field specifies the time at which the event comes into effect. As defined in the DOM 3 Events specification [DOM3EV] if this field is not specified, it MUST always be set to zero.

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.

4.2. Processing unknown events

The are two types of unknown events:

• Events the names of which do not match any known event in the version of the specification supported by the user-agent.
• Events which the user-agent understands as being defined in the specification but that have no meaningful effect within the context in which the user-agent operates (e.g. a mousemove event on a device that has no pointer device cursor).

When encountering an unknown even, a user-agent MUST ignore the entire <event> element and all its descendants.

4.3. Processing unsupported node types

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' attribute points to one such node type, either directly (i.e. at the end of the target path) or indirectly (i.e. as a step in the target path).
• In the payload of the <event> element.

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 <event> element and all of its descendants.

If the payload of the <event> element contains node types that are not supported by the user-agent's DOM implementation the payload MUST be modified so that nodes that have no usable representation in the user-agent's DOM implementation are removed. For instance, given an SVG Tiny 1.2 MicroDOM [SVGT12], processing instructions would be removed as they can have no known impact or representation in the tree, but text nodes would not: they may not have an object type corresponding to them but they are still accessible through the textContent interface. If removing these nodes from the payload causes the payload to become empty, then the entire <event> element MUST be ignored since no useful Event object could be derived from it.

5.1. Unknown elements

There are three categories of unknown elements:

• Elements in foreign namespaces (namespaces that are not the REX namespace)
• Elements in the REX namespace with unknown local names
• Elements in the REX namespace with known local names, but located in places where the grammar does not allow them

Outside of <event> payloads, when encountering an unknown element a user-agent MUST ignore it together with all of its attributes and descendant nodes.

Inside <event> payloads, all elements whether they are in the REX namespace or not are considered to constitute the content of that event, and MUST be processed as if they were in a foreign namespace. REX elements in event payloads MUST NOT be processed as REX elements.

5.2. Unknown attributes on REX elements

There are two types of unknown attributes that MAY occur on REX elements:

• Attributes in a namespace that is not the XML namespace as defined in the Namespaces in XML specification [XMLNS]
• Attributes in no namespace that are not known to be allowed on the element on which they occur

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.

6.1. Errors specific to the DOM or to the target language

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:

DOM errors

If the modification corresponds to something that is invalid in the DOM (e.g. inserting an element after the root element node) then the event is ignored.

Target language errors

If the modification causes the target language to find itself in a state that is erroneous according to its specification, the modification takes place regardless and the error is handled by the mechanisms prescribed in the specification of the host language, as if the modification had been performed through script manipulation of the DOM. The exception to this rule is if such a modification being performed by using the DOM directly had caused an exception to be raised: in that case the error is treated as a DOM error, and the event is ignored.

6.2. Ignored events and elements

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.

7.1. Defining the Reference Event

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 <event> element that has a 'timeRef' attribute set to 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 <event> element has both a 'timeStamp' attribute and a 'timeRef' attribute set to anchor, then the 'timeStamp' attribute MUST be ignored, and the event processed as if it hadn't been specified.

When no reference event has yet been seen, the time from which time stamps are offset defaults to the beginning of the session.

7.2. The 'timeRef' attribute

The 'timeRef' attribute is used to mark an event as a reference event for the timing for time stamps. It has two values, 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 <event> element is untouched. The absence of this attribute is equivalent to it being set to implicit.

<define name='timeRef.AT' combine='interleave'>
  <optional>
    <attribute name='timeRef'>
      <choice>
        <value>implicit</value>
        <value>anchor</value>
      </choice>
    </attribute>
  </optional>
</define>

7.3. The 'timeStamp' attribute

The 'timeStamp' attribute contains a non-negative integer which defines the time in ticks relative to the current reference event at which the event is to be triggered. A tick is defined against the synchronisation clock, which defaults to making a tick last exactly one millisecond, but MAY be set to another value in a user-agent dependent manner (e.g. because the user-agent is synchronising with an audio or video stream that has a different time, or because the user has requested that time run slower or faster).

<define name='timeStamp.AT'>
  <optional>
    <attribute name='timeStamp'>
      <data type='nonNegativeInteger'/>
    </attribute>
  </optional>
</define>

7.4. Tuning in to an event stream

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 ability to send the same message several times (carouselling) so that important content can be guaranteed to be available promptly to the user-agent, and also to compensate for network errors;
• the ability to identify that a given message has been processed already in order to save processing time and to avoid applying the same action multiple times;
• the ability to distinguish between a message that is immediately usable, and one that is a delta that is only meaningful if the previous content that it refers to has also been received.

The above functionality is obtained through the use of two attributes on the <rex> element, 'seq' and 'target' :

<define name='rex.AT' combine='interleave'>
  <optional>
    <attribute name='seq'>
      <data type='integer'/>
    </attribute>
  </optional>
  <optional>
    <attribute name='target'>
      <data type='integer'/>
    </attribute>
  </optional>
</define>

Attributes list

seq

This attribute is a positive integer that identifies a REX message uniquely within a given session. If, within a session, a user-agent receives a messages with a 'seq' that it has already seen for that session, then it SHOULD ignore the entirety of that message. Within a stream of messages that is intended to support tune-in, all messages SHOULD have a 'seq' attribute. This attribute has no default value, and if a message does not have a 'seq' attribute then it MUST be processed normally and cannot be ignored.

target

This attribute is a positive integer that identifies a message that cannot be usefully processed without having received the the message the 'seq' of which has the number that is the value of the 'target' attribute. If a user-agent receives a message with a 'target' that doesn't correspond to a 'seq' that it has seen then it SHOULD ignore the entire message. User-agents are only required to remember the number of the last 'seq' that wasn't accompanied by a 'target' , therefore content SHOULD only use 'target' attributes that refer to the latest standalone 'seq' value.

This functionality can be used as follows. A message containing enough of the document for tune-in would be transmitted with a 'seq' and no 'target' :

<rex xmlns='https://www.w3.org/ns/rex#' seq='1'>
	<event target='/' name='DOMNodeInserted'>
	  <svg xmlns='https://www.w3.org/2000/svg'>
	    <!-- more content -->
	  </svg>
	</event>
</rex>

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.

<rex xmlns='https://www.w3.org/ns/rex#' seq='2' target='1'>
	<event target='id("dahut")' name='DOMAttrModified' attrName='fill' newValue='red'/>
</rex>

Therefore, in a broadcast or multicast environment one may see sequences of events similar to the following:

1. REX message seq=1: creating new document A
2. REX message seq=2, target=1: update document A
3. REX message seq=1: creating new document A (ignore if seen)
4. REX message seq=3, target=1: update document A
5. REX message seq=2, target=1: update document A (ignore if seen)
6. REX message seq=3, target=1: update document A (ignore if seen)
7. REX message seq=4: creating new document B
8. REX message seq=5, target=4: update document A
9. REX message seq=6, target=4: update document A
10. ...

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.

8.1. Mapping Mutation Events to objects

In processing an <event> element that captures a mutation event, the user-agent MUST produce a MutationEvent object, and MUST inform the fields of the object in the following manner:

relatedNode

Set dynamically by the user-agent according to the DOM 3 Events specification [DOM3EV]. For attribute modifications applying to DOM subsets that do not have a representation for Attr nodes this field MUST be null.

prevValue

Set dynamically by the user-agent to hold the previous value for applicable events, as per DOM 3 Events [DOM3EV].

newValue

Set to the value of the 'newValue' attribute for 'DOMAttrModified' and 'DOMCharacterDataModified' events.

attrName

The name of the attribute being added, changed, or removed for 'DOMAttrModified' , as obtained from the 'attrName' attribute when applicable.

attrChange

Set to match the value of the 'attrChange' attribute when applicable.

8.2. The 'DOMSubtreeModified' event

The DOMSubtreeModified is not supported. Implementations SHOULD process it as an unknown event.

8.3. The 'DOMNodeInserted' 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 <event> elements, and the 'position' MUST be incremented by one for each.

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 <event> element MUST allow arbitrary XML as its content. This is not specified in the schema fragment below but left to compounding schemata (e.g. using NVDL) to define.

<define name='DOMNodeInserted'>
  <optional>
    <attribute name='position'>
      <data type='integer'/>
    </attribute>
  </optional>
</define>

Attributes list

position

Specifies the position at which the payload MUST be inserted in the target element's child nodes such that a hypothetical call to 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 'DOMNodeInserted' events MUST NOT be normalised prior to insertion and therefore that indentation, if undesirable in the targeted result, has to be absent from the event payload as well. For instance, given the following target tree:

<document>
  ...
  <section xml:id='poodle-mania'>
    <title></title>
    ...
  </section>
  ...
</document>

And given the following 'DOMNodeInserted' event:

<rex xmlns='https://www.w3.org/ns/rex#'>
  <event target='id("poodle-mania")/title' name='DOMNodeInserted'>
    Poodles are for maniacs!
  </event>
</rex>

Will produce the following result:

<document>
  ...
  <section xml:id='poodle-mania'>
    <title>
    Poodles are for maniacs!
  </title>
    ...
  </section>
  ...
</document>

And not what some may have expected:

<document>
  ...
  <section xml:id='poodle-mania'>
    <title>Poodles are for maniacs!</title>
    ...
  </section>
  ...
</document>

In order to obtain the above, the white space before and after "Poodles are for maniacs!" would have had to be removed.

8.4. The 'DOMNodeRemoved' event

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 <event> element capturing this has a payload as defined in the 'DOMNodeInserted' event, then a second event MUST be created and dispatched immediately after this event (if the target path resolved to a node-set containing more than one item, then each generated event immediately follows the one dispatched on a given node).

The following parameters MUST be set for the generated event. It is of type 'DOMNodeInserted' . Its target node is the parent of the one pointed to by the current 'DOMNodeRemoved' event, unless the latter was pointing to the root node (using '/') in which case the generated event also points to the root node. Its 'position' is that of the removed node within its siblings, in document order. Its payload is set to be that of the current event.

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 <event> element. When this event is transmitted, the <event> element MUST allow arbitrary XML as its content. This is not specified in the schema fragment below but left to compounding schemata (e.g. using NVDL) to define.

<define name='DOMNodeRemoved'>
  <empty/>
</define>

Attributes list

No additional attributes

8.5. The 'DOMNodeRemovedFromDocument' event

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].

8.6. The 'DOMNodeInsertedIntoDocument' event

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].

8.7. The 'DOMAttrModified' event

The DOMAttrModified event indicates that an attribute has been modified, added, or removed.

When representing a 'DOMAttrModified' event, the <event> element's 'target' attribute MUST point to an element node. That element node is the one on which the attribute pointed to by 'attrName' is to be modified, added, or removed.

If the 'attrChange' attribute is set to removal then the attribute pointed to by the target path and 'attrName' attribute MUST exists, and if it does not the event MUST be ignored. If however it is set to modification or addition then there are two possible options:

• if the attribute exists, then the event MUST be processed as if the value of 'attrChange' were modification;
• conversely, if the attribute does not exist, then the event MUST be processed as if the value of 'attrChange' had been 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 <event> element.

<define name='DOMAttrModified'>
  <group>
    <attribute name='attrName'>
      <text/>
    </attribute>
    <optional>
      <attribute name='attrChange'>
        <choice>
          <value>modification</value>
          <value>addition</value>
          <value>removal</value>
        </choice>
      </attribute>
    </optional>
    <optional>
      <attribute name='newValue'>
        <text/>
      </attribute>
    </optional>
  </group>
</define>

Attributes list

attrName

The name of the target attribute on the context element. Its value is a QName resolved in the same manner as QNames in XSLT [XSLT]. Specifically, if the QName does not have a prefix, then the namespace URI component of the name is 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 <event> element being processed; inclusive of the implicit declaration of the prefix 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.

attrChange

Indicates the type of change that concerns this attribute, one of 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.

If the value is modification, then the 'newValue' attribute MUST be present, and the value of the target attribute MUST be changed to be that contained in 'newValue' . If 'newValue' is not specified, the event MUST be ignored. If the target attribute does not exist, the event MUST be processed as if 'attrChange' had had a value of addition.

If the value is addition, then the 'newValue' attribute MUST be present, and the value of the target attribute MUST be created with a value being that contained in 'newValue' . If 'newValue' is not specified, the event MUST be ignored. If the target attribute already exists, the event MUST be processed as if 'attrChange' had had a value of modification.

If the value is removal, then the target attribute MUST be removed. If the target attribute is not present, then the event MUST be ignored. If 'newValue' is specified then it MUST be ignored.

newValue

Specifies the value that the attribute is set to, for values of 'attrChange' for which a value is required.

8.8. The 'DOMCharacterDataModified' event

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 'DOMCharacterDataModified' event, the <event> element's 'target' attribute MUST therefore point to a text node, a comment node, or a processing instruction node. If the node pointed to by the target path does not exist then the event MUST be ignored.

Note that as specified in DOM 3 Events [DOM3EV] this event MUST be dispatched after the node has been modified.

<define name='DOMCharacterDataModified'>
  <attribute name='newValue'>
    <text/>
  </attribute>
</define>

Attributes list

newValue

Specifies the value that the character data is set to. This attribute is required, if it is absent the event MUST be ignored.

8.9. Mutation name events

Neither of the mutation name events (DOMElementNameChanged and DOMAttributeNameChanged) is supported. Implementation SHOULD process them as unknown events.

9.1. Parsing attribute values

The parsing of attribute values MUST be performed as follows:

• The white space in attribute values MUST be normalised such that XXX.
  the rules here must be defined better, see other specs
• Attribute values are case-sensitive. If the value of an attribute can be understood as being case-insensitive in a given vocabulary that they are being applied to (e.g. a 'target' attribute's path applying to an HTML document) then it is up to the user-agent to map the case-sensitive value that it receives to one that may operate on the target vocabulary.

9.2. Conformance to the QA Framework Specification Guidelines

This section is informative.

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.

9.3. Optional features

There are two features for which optionality is to be found:

Processing XML as a stream

There are two major manners in which XML may be processed: either the processor performs actions as soon as a given token in the source is parsed (this is generally referred to as processing in a "streaming" fashion), or the entire document is first parsed into an in-memory representation and then walked through to perform actions (a.k.a. tree-based processing). The major difference between the two as far as this specification is concerned is that an implementation processing XML in a streaming fashion will dispatch events that it has parsed in their entirety immediately even if there is an XML well-formedness error further into the document, whereas tree-based processing will detect the well-formedness problem before any action is taken. Since it is preferable at least for performance reasons to process documents in a streaming manner, the specification recommends that approach but does not mandate it. We did not wish to enforce only one kind, as both may be impractical, if only because some constrained devices will only have one type of processing or the other.

Support for varied DOM representations

This specification has be created with the goal of being reusable in many situations, notably in case in which the DOM support of the user-agent may vary greatly, and in fact in some cases be to some degree absent (which is to say, there needs to be a tree representation that can usefully be understood as a DOM, but it need not be exposed for instance to scripting). To enforce this would have severely reduced the applicability of this specification. Instead, it describes normatively how to handle node types that cannot be usefully represented in the user-agent's DOM of choice.

11.1. Introduction

This appendix registers a new MIME media type, "application/rex+xml" in conformance with RegMedia and W3CRegMedia.

11.2. Registration of Media Type application/rex+xml

MIME media type name:

application

MIME subtype name:

rex+xml

Required parameters:

None.

Optional parameters:

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.

Encoding considerations:

Same as for application/xml. See RFC 3023 [RFC3023], section 3.2.

Restrictions on usage:

None

Security considerations:

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.

Interoperability considerations:

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.

Published specification:

This media type registration is extracted from Appendix A of the REX 1.0 specification.

Additional information:

n/a

Person & email address to contact for further information:

Robin Berjon (member-rex-media-type@w3.org).

Intended usage:

COMMON

Author/Change controller:

The REX specification is a joint work product of the World Wide Web Consortium's SVG and Web APIs Working Groups. The W3C has change control over this specification.