RE: [xml-dev] "Introducing MicroXML, Part 1: Explore the basicprinciples

["Rushforth, Peter" <Peter.Rushforth@NRCan-RNCan.gc.ca>]

Hi John,

>What specifically do you want to see.  "Reliable hypermedia affordances"
>is a rather abstract notion.

It's not abstract at all.

If we look at what goal # 1 of XML is:

1. XML shall be straightforwardly usable over the Internet.

and some of Rick Jeliffe's description of the motivation for that:

"SGML had a particular issue that it was, by design, retargetable. Before Unicode and the URLs, every different system had different character sets and different ways of locating files. So SGML provided a mechanism for labelling that an entity (resource) would need some system-specific fix in order to be useful, and a mechanism for naming entities regardless of their location (PUBLIC identifiers.
Because of this goal, SDATA entities were removed from SGML as was the use of unresolved entities (entities PUBLIC identifiers with no SYSTEM identifiers.) It was unfeasible to expect users to fix document to suit their local systems: that is geekstuff. The use of Unicode and URLs was a non-brainer from this goal."

It is clear that XML needs  hypermedia affordances which are fixed and carry web semantics so that not just parsers, but applications can count on their semantics.  On the Web, that means browsers, crawlers and http: REST.

So, a core set of link and protocol related attributes should be added to the xml: namespace.
The set and the semantics of the set is driven by the web, not by C pointers or what have you.  Below is an xml schema which documents them, as I see it.  I think adding them to the XML namespace is backwards compatible.

Then, for example, browsers which load an XML document via application/xml, could recognize the links and possibly act on them for the application which would be likely javascript but now could be XSLT, thanks to Saxonica.

Respectfully,
Peter Rushforth

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"; elementFormDefault="qualified" targetNamespace="http://www.w3.org/XML/1998/namespace"; xmlns:xml="http://www.w3.org/XML/1998/namespace";>
<xs:attribute name="href" type="xs:anyURI">
<xs:annotation>
<xs:documentation>Almost self explanatory. That's a standard at its shared understanding best. Legal values according to RFC 3986.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="tref" type="xs:string">
<xs:annotation>
<xs:documentation>The tref attribute is a "templated link". The reason that a separate attribute is required is because the value of an href is expected to be a legal URI, which excludes templated links which follow RFC 6570 because of the use of non-URI characters. In reflecting on templated links, it is likely a good idea to use URI templates in a tref attribute anyway, as this will maximize the possibility of a cacheable response due to the encoding of the order of parameters, as well as their case. In "Building Hypermedia APIs with HTML5 and Node. Building Hypermedia APIs with HTML5 and Node", by M Amundsen, ISBN: 9781449309497, p16, an HTML FORM is used to describe the LT H-Factor. FORMs do not leverage the URI Templates RFC 6570, so it may be possible that URIs composed by application of FORM elements don't follow a predictable parameter order (say this is managed differently by different user agents(?)) hence, may result in less than optimal cacheability of responses. Once processed by a link template processor, value would be a legal URI per RFC 3986.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="src" type="xs:anyURI">
<xs:annotation>
<xs:documentation>The src attribute is a URI per RFC 3986, to a resource which is meant to be part of the current resource. So it combines href with @rel="partof" or something like that. This has been the subject of much debate since the beginning of time. In any case, it has a specific composition semantic around the URI it contains. Since it exists, it might be necessary to also have tsrc attribute to match the tref attribute, but this seems to me to be taking a path similar to what was the subject of the debates above. So, not going there, just use tref if you need to and once the link is composed, use a @rel associated with the tref to define if it's a composition or not (in your media type definition).</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="rel">
<xs:annotation>
<xs:documentation>What is the meaning of a rel value? I believe the intention is to communicate the relation of the linked-to resource to the current representation. RFC 5988 allows a rel to have &gt; 1 token, whereas atom limits it to 1. What is the effect/meaning of &gt; 1 value?</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:union memberTypes="xs:anyURI xs:token"/>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="type" type="xs:string">
<xs:annotation>
<xs:documentation>A media type, per RFC 2046.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="hreflang" type="xs:language">
<xs:annotation>
<xs:documentation>See xml:lang for acceptable content specification.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="method" type="xs:token">
<xs:annotation>
<xs:documentation>An HTTP method, per RFC 2616 section 9.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attributeGroup name="LinkOutboundAttGroup">
<xs:attribute ref="xml:href"/>
<xs:attributeGroup ref="xml:LinkAnnotationControls">
<xs:annotation>
<xs:documentation>The set of LinkAnnotationControls in this media type specification includes only a 'core' group which are needed for RESTful interactions on the Web.</xs:documentation>
</xs:annotation>
</xs:attributeGroup>
</xs:attributeGroup>
<xs:attributeGroup name="LinkEmbeddedAttGroup">
<xs:attribute ref="xml:src"/>
<xs:attributeGroup ref="xml:LinkAnnotationControls">
<xs:annotation>
<xs:documentation>One of the reasons to *have* a @src attribute is to avoid having to decorate the link because the @src name implies the rel, type and language. But since they are optional here: if you need them, then use them.</xs:documentation>
</xs:annotation>
</xs:attributeGroup>
</xs:attributeGroup>
<xs:attributeGroup name="LinkTemplateAttGroup">
<xs:attribute ref="xml:tref"/>
<xs:attributeGroup ref="xml:LinkAnnotationControls"/>
</xs:attributeGroup>
<xs:attributeGroup name="LinkIdempotentAttGroup">
<xs:attribute ref="xml:href"/>
<xs:attributeGroup ref="xml:LinkAnnotationControls"/>
</xs:attributeGroup>
<xs:attributeGroup name="LinkNonIdempotentAttGroup">
<xs:annotation>
<xs:documentation>Examples of Non idempotent hypermedia affordances are certain configurations of the html form element, and the atom publishing protocol collection element, which also acts like a form. In short, non-idempotent links seem to require more elaborate hypermedia affordances to correctly interact with them. So recommended practice would be to re-use the hypermedia affordances defined in this specification, and combine them with markup specific to the media type, and document the completed affordance appropriately in the media type documentation. This is similar to what is recommended in "Building Hypermedia APIs with HTML5 and Node. Building Hypermedia APIs with HTML5 and Node", ISBN: 9781449309497, on page 17.</xs:documentation>
</xs:annotation>
<xs:attribute ref="xml:href"/>
<xs:attribute ref="xml:tref"/>
<xs:attributeGroup ref="xml:LinkAnnotationControls"/>
</xs:attributeGroup>
<xs:attributeGroup name="LinkAnnotationControls">
<xs:annotation>
<xs:documentation>According to "Building Hypermedia APIs with HTML5 and Node. Building Hypermedia APIs with HTML5 and Node", ISBN: 9781449309497, a CL, or Link Annotation Control, provides inline metadata for the links themselves. The data allows clients to locate and understand the meaning of links themselves. The best example is that defined by RFC 5023, link@rel="...", where the @rel decorates the uri and indicates to the recipient that the URL has a defined meaning (defined by the media type specification) in the context of the containing response. Curiously, RFC 5988 Web Linking allows a link to contain multiple @rel values, whereas RFC 4287 The Atom Syndication Format allows only a single @rel value. I believe there was a bit of debate in the atom working group as to whether this should be a "one or more" construct or simply an "only one"; the latter is the final outcome. This begs the question: what is a @rel value? What is the effect on the URI? While any given mime type may decide to add other controls beyond @rel, it is the most common example that is useful. Other examples of the CL factor include XLink's extended set of attributes, which are widely not understood because of their complexity.</xs:documentation>
</xs:annotation>
<xs:attribute ref="xml:rel"/>
<xs:attribute ref="xml:type"> </xs:attribute>
<xs:attribute ref="xml:hreflang"/>
</xs:attributeGroup>
<xs:attributeGroup name="MethodControls">
<xs:annotation>
<xs:documentation>The last but not least hypermedia affordance is the method attribute, which comes from the most successful hypermedia format on the planet. So, xml will unashamedly follow the lead of HTML on this attribute. Use sparingly, otherwise your hypermedia may get so complex as to be unimplementable!</xs:documentation>
</xs:annotation>
<xs:attribute ref="xml:method"/>
</xs:attributeGroup>
<xs:complexType name="ProtocolControls">
<xs:annotation>
<xs:documentation>These hypermedia affordances contain 'hints' eg @type as to what values to use in protocol headers and methods.</xs:documentation>
</xs:annotation>
<xs:attributeGroup ref="xml:LinkAnnotationControls">
<xs:annotation>
<xs:documentation>This group contains ReadControls and UpdateControls as desribed in Building Hypermedia APIs with HTML5 and Node. Building Hypermedia APIs with HTML5 and Node, ISBN: 9781449309497 on p18. They can not be represented when they both have the same content model, since xml schema thinks they conflict, but obviously a read can`t be a write so if we simply represent both with the LinkAnnotationControl we achieve the same goal, which is to allow authors to mark up their elements to designate them as read or write hypermedia affordances as required.</xs:documentation>
</xs:annotation>
</xs:attributeGroup>
<xs:attributeGroup ref="xml:MethodControls">
<xs:annotation>
<xs:documentation/>
</xs:annotation>
</xs:attributeGroup>
</xs:complexType>
<xs:attributeGroup name="ReadControls">
<xs:annotation>
<xs:documentation>See documentation for the ProtocolControls complex type.</xs:documentation>
</xs:annotation>
</xs:attributeGroup>
<xs:attributeGroup name="UpdateControls">
<xs:annotation>
<xs:documentation>See documentation for the ProtocolControls complex type.</xs:documentation>
</xs:annotation>
</xs:attributeGroup>
</xs:schema>