W3C home > Mailing lists > Public > public-linked-json@w3.org > August 2013

Defining a common convention for marking up JSON

From: Michael Pizzo <mikep@microsoft.com>
Date: Tue, 27 Aug 2013 20:51:48 +0000
To: "public-linked-json@w3.org" <public-linked-json@w3.org>
Message-ID: <78a4f308f60548149e808c473573eb87@BN1PR03MB220.namprd03.prod.outlook.com>
Dear JSON-LD Community;

JSON-LD, OData's JSON format, and other formats built on JSON are trying to do very similar things (add "markup" to a JSON payload for things like ids, types, etc.). Unfortunately, since JSON doesn't define a way to differentiate properties from markup, each specification invents its own naming conventions to differentiate properties from markup.

We have a real opportunity to align efforts here in defining a common convention for marking up JSON payloads.

JSON-LD adds markup to JSON payloads by defining a set of keywords that begin with the "@" symbol. JSON-LD parsers understand these keywords and treat them differently than other properties.

OData's JSON format separates properties from markup through a namespacing mechanism similar to XML. Properties that contain a dot (.) (which most JSON parsers already treat differently) are "namespace qualified" names - the prefix before the dot is the namespace and the part after the last dot is the keyword within that namespace.

This general mechanism allows anyone to extend a JSON payload with "markup", and JSON clients to differentiate markup from data, and ignore markup that they don't know/care about.

OData uses this *general mechanism* to add odata-specific markup, defined in the "odata" namespace. So "odata.id" is clearly recognized as the id keyword defined by the OData specification, and "odata.type" is clearly recognized as the type keyword defined by the OData specification (there is clearly an opportunity to align in some of these moving forward, but for right now I'm more interested in having a common "markup" convention).

Following this same common convention, JSON-LD could mark up a payload as:

{
  "jsonld.context": "http://json-ld.org/contexts/person.jsonld",
  "jsonld.id": "http://dbpedia.org/resource/John_Lennon",
  "name": "John Lennon",
  "born": "1940-10-09",
  "spouse": "http://dbpedia.org/resource/Cynthia_Lennon"
}

Regardless the syntax, providing a common convention for namespace qualifying "markup" keywords give us a real opportunity to foster consistency, reuse, and interoperability.

Both JSON-LD and OData are close to releasing an initial standard (OData has just progressed to a Committee Specification in OASIS), so the window is very close to closing on alignment, but the potential upside could be huge. Imagine being able to mark up the same JSON payload with JSON-LD keywords, odata keywords, and other "annotations". JSON parsers would have a common way to differentiate markup from data, and could consume/ignore/expose whatever markup they chose.

Would the JSON-LD community be open to working with the OData community to agree on a standard, extensible, namespaced mechanism that all JSON-based formats could use to extend JSON?

I hope so, and eagerly await your thoughts.

Sincerely,

Michael Pizzo
Editor, OASIS OData JSON Specification
Received on Wednesday, 28 August 2013 06:57:50 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 16:18:39 UTC