« Code overloadBest of PyCon 2009 »

Somebody needs to discover JSON


Permalink 10:24:41 am, by fumanchu Email , 356 words   English (US)
Categories: IT

Somebody needs to discover JSON

In The text/plain Semantic Web, Benjamin Carlyle argues:

Perhaps the most important media type in an enterprise-scale or world-scale semantic web or REST architecture is text/plain. The text/plain type is essentially schema free, and allows a representation to be retrieved or PUT with little to no jargon or domain-specific knowledge required by server or client. It is applicable to a wide range of problems and contexts, and is easily consumed by tools and humans alike.

Substitute 'application/json' and that paragraph starts to make sense. But then, the author also says "To my mind the best resource in formatting and processing of simple text-compatible data types can be found in the specification for XML Schema." So perhaps I shouldn't be too hard on the poor refugee. He comes tantalizingly close:

Part of the problem that emerges is that text/plain is not specific enough. It doesn't have sub-types that are clearly tied to a specification document or standards body. This makes interoperability a potential nightmare of heuristic detection.


Another problem with using text/plain in its bare form is its default assumption of a US-ASCII character type. This can lead to obvious problems in a modern internationalised world.

Both of which JSON solves nicely: it has basic types and SHALL be encoded with a Unicode encoding (utf8 by default).

Again, ideally we would be making use of a well-defined standards body to own and maintain the media types used to communicate very basic information.

The IANA and IETF sound like well-defined standards bodies to me...

Perhaps the clearest indication that you are overusing text/plain is that you are experiencing an explosion in hyperlinks. When you start to need a document to provide links for consumers to find these text/plain-centric resources, you should probably consider incorporating the information directly into these documents themselves.

A. Hyperlinks are a Good Thing.

B. You should first consider providing hyperlinks in a machine-discoverable fashion; text/plain is not it. A nice version of "it" is using XHR to GET/PUT application/json resources.

C. Allow comments on your blog.


Comment from: Jess [Visitor] Email

Do you have an opinion about URLs in JSON documents? Is it enough to put an "http://"-prefixed string in an expected place (i.e., a given member of an object)? Or do URLs not belong here at all?

05/05/09 @ 12:20
Comment from: fumanchu [Member] Email

URL's certainly belong in JSON, just like they belong in any RESTful protocol built on HTTP. See http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven for the rationale.

I wrote http://www.aminus.org/rbre/shoji/shoji-draft-01.txt to help encourage URL's in JSON. There are basically 3 ways to do it:

* Put hyperlinks in special places, which is what Shoji does.
* Markup hyperlinks with a special syntax that can appear anywhere.
* Use a separate schema resource that describes which data are hyperlinks.

Note that all 3 are defined by the MIME type of the response, not just convention.

05/05/09 @ 16:09
Comment from: Jess [Visitor] Email

But in that case you're not using just 'application/json', right? Do you have a way of indicating that consumers unfamiliar with 'application/shoji' should just fall back on 'application/json'? If I weren't worried about reuse, I would just make sure the pages in my app knew the idiosyncratic rule I made up for finding URLs, which I think would not be perfectly RESTful.

I guess that I'd like to see your special syntax option as a part of JSON: the definition should include a URI literal. (and while we're at it, a date literal, etc... ack, this way lies microformats!)

05/06/09 @ 10:42
Comment from: Benjamin Carlyle [Visitor] · http://soundadvice.id.au/blog/

json is useful in exactly the same circumstances where XML is useful: Where you want to convey a structured document that can be interpreted by a machine that is aware of the document's structure.
Plain text is useful in a different context: Where you want to convey an atomic element of information (eg number, string, datetime).
json is especially useful in web browsers. That's not my field. My field is REST architecture, especially where machines have to interact with each other without the assistance of a human being. They must do so in a way that maximises intrinsic interoperability, and is backwards compatible over long spans of time.
Plain text alongside a specific set of targeted media types (be they formatted in xml, jason, or otherwise) form a useful set of foundational media types for conveying information between machines. I am not inclined to wrap up an integer as { value: 1234 } any more than I am inclined to wrap it up as <value>1234</value>. Both of these encodings get in the way of the original intent, which is to convey a bare number.
In addition, application/json as a media type is no more useful in REST architecture (with its constrained methods -and- media types) than application/xml is. This has nothing to do with json or XML, and everything to do with self-description: I can't select between different json formats or different xml formats using these media type identifiers, nor can I tell without additional heuristics which of a number of possible variants the document I retrieved happens to follow.
Content negotiation and correct parsing (the whole reasons for assigning media type identifiers) rely on the ability to tell the difference between (say) an rss document and an atom document. If they were both marked as application/json or application/xml, you would have to start inspecting the document to infer which one is which. That is a breach of REST constraints.
The role of plain text as a schema-free media type is again targeted at a different purpose. What I am talking about is not structured documents without the overhead of XML schemas. I am talking about documents with atomic structure that require no further wrapping or obfuscation. If you want to do something as simple as attach a timestamp, a plain text media type is not for you.


05/12/09 @ 06:43

Leave a comment

Your email address will not be revealed on this site.

Your URL will be displayed.

Please enter the phrase "I am a real human." in the textbox above.
(Line breaks become <br />)
(Name, email & website)
(Allow users to contact you through a message form (your email will not be revealed.)
April 2014
Sun Mon Tue Wed Thu Fri Sat
 << <   > >>
    1 2 3 4 5
6 7 8 9 10 11 12
13 14 15 16 17 18 19
20 21 22 23 24 25 26
27 28 29 30      


The requested Blog doesn't exist any more!

XML Feeds

open source blog