Quoderat

Charl van Niekerk has an interesting posting on a topic that should have been be more obvious to me: that the xml:lang attribute (and HTML lang) are critical for making online information accessible to the visually-impaired. Voice synthesizers that read documents aloud need to know what language they’re reading, and it wouldn’t take much effort for us to tell them.

Obviously, this is a less critical issue for data-oriented XML, but even then, XML data often contains large chunks of prose (like product descriptions) that are, eventually, intended for human consumption. I won’t promise to rush and fix all of this today in my existing XML and HTML, but I’m certainly going to try harder in the future.

My first REST design question is about the fact that RESTafarians seem to consider identification and location to be the same thing, and following from that, the question of how to make identification persistent in XML resources. For example, assume that http://www.example.org/airports/ca/cyow.xml is both the unique identifier of an XML data object and the location of that object on the web. That’s the whole point of REST, really. RESTafarians don’t like interfaces where identifiers are hidden inside XML objects returned from POST requests to unrelated URLs, for example (in fact, they get angry in quite an amusing way).

GET and PUT

So, here’s a simple use case. Let’s say that I download the XML data file at http://www.example.org/airports/ca/cyow.xml and it looks like this simple example:

<airport>
 <icao>CYOW</icao>
 <name>Macdonald-Cartier International Airport</name>
 <political>
  <municipality>Ottawa</municipality>
  <region>ON</region>
  <country>CA</country>
 </political>
 <geodetic>
  <latitude-deg>45.322</latitude-deg>
  <longitude-deg>-75.669167</longitude-deg>
  <elevation-msl-m>114</elevation-msl-m>
 </geodetic>
</airport>

I then copy it onto a USB memory stick, bring it home from work, copy it onto my notebook computer, and work on it while offline during a business flight. The file no longer has any direct connection with its URL: it has gone through other transfers since the HTTP GET request I used to download it. How do I know what I’m working on or where I should PUT it when I’m done?

If this information has to be kept out of line, then some of REST’s advantages are evaporating, because now I have to start using custom-designed clients again instead of simply piggybacking on existing web technologies. As an identifier, the URL is clearly part of the resource’s state, and belongs in the XML data file; as a location, however, it is superfluous information and belongs only in the protocol (HTTP) level.

Where does the document identifier go?

Let’s assume that I get over my squeamishness and decide that the URL is a proper identifier and belongs in the XML representation. Now, how do I do that in a fairly generic way? xml:id is out of the question, since it’s designed only to hold an XML name for identifying part of a document, not a URL to identify an entire document. I could use (or abuse) xml:base, like this:

<airport xml:base="http://www.example.org/airports/ca/cyow.xml">
 ...
</airport>

I’m not certain, though, how XLink processors would deal with that. Would the relative URL “cyyz.xml” end up being resolved to http://www.example.org/airports/ca/cyyz.xml or http://www.example.org/airports/ca/cyow.xmlcyyz.xml? There’s also the possibility that some highly-cooked APIs might predigest the xml:base attribute so that application code never sees it. Do the XML standards people believe this kind of an xml:base usage is legit?

If xml:id is unusable, and xml:base is problematic, it looks like there might be no standard way to identify RESTful XML documents, and each XML document type will need its own ad-hoc solution. Any suggestions? Does the world need one more xml:* attribute (I hope not)?

I’d be interested in hearing how REST developers have dealt with identifier persistence and round-tripping when the identifier is the URL.

[Update: fifth and final question added] I’ve been thinking a bit about REST recently while working on a new data-oriented application. REST in its now-broadened meaning is easy to explain: pieces of data (likely XML-encoded) sit out there on the web, and you manipulate them using HTTP‘s GET, PUT, and DELETE methods (practically CRUD, except that the Create and Update parts are combined into PUT). Try explaining SOAP, much less the essence of the whole WS-* family in one easy sentence like that, and you’ll see the difference.

This very simplicity should raise some alarm bells, though. RDF also has an apparently simple data model, but for RDF 1.0, at least, the model turned out to be painfully incomplete, as I found out when I implemented my RDF parsing library. Is REST hiding any of the same traps? RESTafarians point out that REST is the basis of the Web’s success, but that’s really only the GET part (and its cousin, POST). Despite WebDAV, we have very little experience using PUT and DELETE even for regular web pages, much less to maintain a data repository. Even the much-touted RESTful web services from Amazon and eBay are GET-only (and POST, in eBay’s case); in fact, many, if not most firewalls come preconfigured to block PUT and DELETE, since web admins see them mainly as security holes.

My gut feeling is that REST is, in fact, more manageable than XML-RPC or WS-* for XML on the Web, but that we have a lot of issues we’ll need to work out first. Data management is never really simple, and while WS-* makes it harder than it has to be, even the simplest REST model cannot make it trivial. I’m going to post some of my own questions about REST design from time to time in this weblog, as I think of them, and I’ll look forward to hearing from people who have already dealt with or at least thought about these problems on their own.

Here are my questions so far:

• REST design question #1: identification
• REST design question #2: listing and discovering resources
• REST design question #3: the meaning of a link
• REST design question #4: how much normalization?
• REST design question #5: the “C” word (Content)

[Updated: see below] Norman Walsh has just posted an unusual essay. The gist of it seems to be that the W3C (at some level) has decided to modify the xml:id specification (released only days ago as a Candidate Recommendation, as I mentioned here) — there is some other specification (not named) that has a bug, most likely an incorrect closed enumeration of all the possible attributes in the XML namespace. At some level, the W3C has decided that the attribute will be renamed to the unqualified xmlid to avoid upsetting the people who messed up the other spec.

Norm sounds mad, and I don’t blame him. I remember when I was on the original XML working group and we were ordered from above to rewrite the XML Namespaces spec substantially for extremely questionable reasons (mainly the ability to embed XML inside non-XML HTML documents for v3 browsers — seriously).

[Update: Norm has revised the essay, adding enough extra information to the essay to let us figure out the problem — it has to do with the interaction between the XML Canonicalization (C14N) and xml: attributes, where C14N mistakenly assumes that all xml: attributes should be automatically inherited. Here’s the official request to deal with the issue.

I had already mentioned the incompatibility with C14N in my first posting on xml:id, then forgot it completely when reading Norm’s essay. So far, this is just a dispute, not a done decision.]

Anne van Kesteren’s is the first report to reach me that the W3C’s xml:id spec has just moved up the food chain to Candidate Recommendation. I’m usually one of the first people to whine about too many XML-related specs, but I think this is a good one, despite a few minor problems like an incompatibility with XML Canonicalization.

Why does this matter? Any use of XML over the web that requires DTD or schema processing is broken because of all the extra security and availability risks involved in processing external files, especially when they’re hosted at other sites. The xml:id spec gives a quick and dirty way of identifying parts of an XML document without requiring a schema, DTD, or even a namespace declaration (since the xml: prefix is predeclared for XML documents). Basically, you just use something like this inside your XML document:

<employee xml:id="dmeg123">
 <name>David Megginson</name>
 <role>Housekeeping</role>
</employee>

and you’re done. Other XML documents can refer to part of yours using a fragment identifier, as in http://www.example.org/employees.xml#dmeg123, and that’s that — no schemas are harmed in the making of this link. I don’t know if XML data on the web ever will take off, but this small spec is a critical step in the right direction. Congrats to the editors and the working group for pushing it through this far.

If only we could make everything in XML this simple.