It so happens that my name on is the front page of Namespaces in XML 1.0, a technology which is pretty broadly disliked. Well, it seemed like a good idea at the time. But I think we’ve learned some useful things since then and can make some good consensus recommendations for people doing this kind of thing, especially if they’re using JSON.

Problems of History · A good place to start brushing up on this would be with James Clark’s recent XML Namespaces. James is authoritative on technology, but I’m going to quibble with his take on history: “the argument for naming namespaces with URIs is that you can do a GET on the URI and get something human- or machine-readable back that tells you about the semantics of the namespace.” I’m not sure. I recall it more simply: namespaces needed to have names and over at the Web consortium, it’s basic dogma that whenever you’re naming things, you should name them using URIs unless there’s a good reason not to. The benefits of using URIs are many and don’t necessarily include using them to retrieve data.

In any case, the rest of James’ argument is well worth reading. I have another approach I’d like to explore here, which is marginal for XML but real interesting for JSON.

Do It Like Java · My Java classes have names like org.tbray.framer.Framer or com.sun.cloud.VM , depending on the context. It’s very unlikely they’ll collide with anything else. We really couldn’t adopt this approach for XML, because the dot “.” had historically been allowed, and commonly used, in SGML element types and attribute names. I bet that, if it hadn’t, we might well have done that.

Especially for JSON · A lot of protocols these days format their messages in JSON, which makes perfect sense if you’re not trying to interchange document-like things. These messages tend to be dictionaries; here’s an example from the Sun Cloud API:

{ "name" : "Database" "uri": "/vdc/m~001", "run_status" : "HALTED", "description" : "MySQL host", "tags" : [ "sql" ] }

In the Sun Cloud API, like in many others, the dictionary keys don’t use any dots. And like many others, there’s a MustIgnore policy. So, while I still have an action item to make this explicit, the extensibility policy is obvious: use java-style names with dots. So if I wanted to add a sun-specific proprietary extension to this particular resource representation, it’d look like this:

{ "name" : "Database" "uri": "/vdc/m~001", "run_status" : "HALTED", "description" : "MySQL host", "tags" : [ "sql" ], " com.sun.cloud.solaris-version " : "2009.06", }

Simple, obvious, and explained in a single short paragraph; I like it a lot.