RE: Defining a common convention for marking up JSON

On Tuesday, September 24, 2013 11:37 PM, Michael Pizzo wrote:
> Picking back up on this thread (how quickly time passes).
> 
> I think we got a bit off track by talking about whether keywords were
"data"
> or "markup". Regardless of whether we consider information like context,
> type, etc., markup, we have the basic problem that we want to add
> information to the JSON payload that doesn't conflict with the data
members
> (or "terms") being serialized.
> 
> The fact that JSON-LD prefixes keywords with "@" and recommends that terms
> NOT start with "@" illustrates the point exactly. We are trying to avoid
> conflicts between term names, keywords, and other potential (important)
> information about the collection of terms.
> 
> Prefixing such "keywords" with "@" works for one definer of keywords
(i.e.,
> those defined by JSON-LD), but if other parties want to add additional
> keywords to the same payload, without conflicting with term names,
JSON-LD,
> OR EACH OTHER, they also have to come up with a convention. Which means
that
> someone wanting to persist terms compatible with multiple systems needs to
> know about, and avoid, multiple conventions.

That goes right to the heart of the question in my last mail:

  Does OData still use application/json as media type? If that's the case,
how
  would a processor know whether this is really intended to be OData or
  whether someone just accidently called a property odata.something? JSON-LD
  doesn't redefine the semantics of existing JSON. It has its own media type
  (application/ld+json) which defines the semantics of those keywords in
such
  a document. If you want to serve it as JSON, you would have to associate a
  context to it (using an HTTP link header with a very specific relation).
So
  there's no risk of overwriting other namespaces as OData does. Everything
is
  visible at the HTTP level.

IMO there simply isn't a problem. If you are using application/ld+json it is
clear which keywords are reserved. If you are using application/json, then
none is reserved at all and every naming scheme you use suffers under the
same problem (you can control the likelihood of collisions but not avoid
it).

So, if someone wants to use OData and JSON-LD in a single payload, I would
propose the following solution. Serve the document as application/ld+json,
define a odata namespace in the context as Alexey proposed in another mail
and call it a day. If you want that those properties are dropped by generic
clients, use a namespace but don't define it.


> Again, if we take the example of XML, one thing XML does very well is
allow
> a payload to be made up of elements defined by multiple different parties,
> with multiple different purposes. By namespacing the element names, these
> elements can all co-exist and processors understand exactly how to process
> the results according to their own set of rules.

You can achieve exactly the same with JSON-LD. There are just a few keywords
which are in the default namespace so to speak. You can define as many other
namespaces as you want.


> JSON-LD and OData are both *so* close to this model. Both JSON-LD and
OData
> are adding properties to the JSON payload that we need to make sure don't
> conflict with the terms being serialized OR EACH OTHER.

That's not entirely true for JSON-LD. Since it has a special media type we
could just as well call drop the @ prefix. The reason why it's there
nevertheless is because we wanted to give people a choice how to name those
things. Having an @ prefix means that it becomes much easier to convert
legacy documents. In JSON-LD you can alias @id to simply id as follows:

{
  "@context": {
    "id": "@id"
  }
  "id": "/this-is-my-identifier"
}

That feature is called keyword aliasing.



> JSON-LD choses
> prefixing keywords with "@" to try and avoid conflicts with term names,
but
> this is not yet common nor general. OData defines a common mechanism of
> qualifying the names to allow multiple different parties to add content
> without conflicts, but relies on the simple presence of a dot in the name
to
> distinguish term names from namespaced keywords (which precludes term
names
> from containing dots).

JSON-LD has exactly the same feature. We adopted XML's notion of CURIEs
(compact IRIs in JSON-LD):

{
  "@context": {
    "mynamespace": "http://example.com/mynamespace#"
  }
  "mynamespace:myproperty": "Here we go"
}


> If we could both bend just a little; if OData would prefix keywords with
> "@odata.*", and JSON-LD would prefix keywords with "@jsonld.*" then we
could
> share a convention for adding keywords that don't conflict with term names
> without conflicting between the two (i.e., @odata.context is different
from
> @jsonld.context). At the same time we could allow other parties to add
> information to the payload (i.e., "@org.iso.unitsofmeasure":"meters") and
> further reduce the likelihood of having term names conflict with any of
> these keywords (i.e., even if there was a term named "@context" it
wouldn't
> conflict with JSON-LD's "@jsonld.context).

And how would a client know what @odata.* or @org... means? Without a
central registry it would be impossible. JSON-LD is based on linked data. So
the idea is that once you expanded all those properties to URLs, you simply
go and look them up. Again, as Alexey already said, you could use that
mechanism to serialize OData as JSON-LD. I'm doing exactly that with Hydra.


> The OASIS OData Technical Committee has signed off on a Committee
> Specification 01 as the final OData specification ready for
standardization.
> I have recommended that the Technical Committee delay standardization by
> producing a Committee Specification 02 that aligns with JSON-LD by
prefixing
> all annotations with "@". So all OData keywords within a JSON payload with
> start with "@odata.", and other annotations that follow the convention
will
> start with "@{namespace}".
> 
> It would be fantastic if JSON-LD would support this convention by
prefixing
> keywords with "@jsonld.*".

Or, given that OData doesn't define a media type as far as I know, we could
say that JSON-LD's keywords are in the default namespace and thus live under
@*.


I think we are not completely understanding each other. I would like to
invite you to our next JSON-LD telecon (next Tuesday). You can find the
necessary details to join at http://json-ld.org/minutes/


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Thursday, 3 October 2013 14:41:11 UTC