RE: JSON a link poor format

Whoops – unbalanced braces. Fixed below.

From: Simon.Cox@csiro.au [mailto:Simon.Cox@csiro.au]
Sent: Monday, 19 October 2015 10:10 AM
To: jeremy.tandy@gmail.com; l.vandenbrink@geonovum.nl; public-sdw-wg@w3.org
Subject: [ExternalEmail] RE: JSON a link poor format

Thanks Jeremy –

Indeed – the approach to linking in OM-JSON is probably more a statement of requirements than a fully resolved solution.
JSON-LD’s “@id” approach might be preferable, particularly (as you point out) it is the only linking mechanism for JSON which is fully and formally defined.

How to mix in the other useful link properties?
In JSON-LD the rel|xlink:arcrole function is satisfied by the property itself.
So we just need to handle ‘title’.
Re-writing the example from the OM-JSON presentation in a more JSON-LD-friendly manner, how does this look?

```
{
    "name": "spec1",
    "sampledFeature": {
        "@id": "http://example.org/featureA", "title": "test feature A"
    },
    "complex": [
        { "http://example.org/parent": { "@id": "http://example.org/sample2", "title": "parent sample" }  },
        { "http://example.org/child": { "@id": "http://example.org/sample3", "title": "child sample"  }  }
    ],
    ...
}
```

Simon


From: Jeremy Tandy [mailto:jeremy.tandy@gmail.com]
Sent: Friday, 16 October 2015 8:01 PM
To: Linda van den Brink <l.vandenbrink@geonovum.nl<mailto:l.vandenbrink@geonovum.nl>>; SDW WG (public-sdw-wg@w3.org<mailto:public-sdw-wg@w3.org>) <public-sdw-wg@w3.org<mailto:public-sdw-wg@w3.org>>
Subject: Re: JSON a link poor format

Hi

Indeed, JSON-LD does resolve the problem of links ...

However, there is some concern that formalism of JSON-LD places an additional burden over an above the use of 'plain-old-JSON' (as I call it) ... so there are still folks out there not wanting to adopt JSON-LD.

Taking a look at some basic concepts in JSON-LD (from [1]):

plain-old JSON =

```

{

  "name": "Manu Sporny",

  "homepage": "http://manu.sporny.org/",

  "image": "http://manu.sporny.org/images/manu.png"

}
```

JSON-LD =

```

{

  "http://schema.org/name": "Manu Sporny",

  "http://schema.org/url": { "@id": "http://manu.sporny.org/" },  ← The '@id' keyword means 'This value is an identifier that is an IRI'

  "http://schema.org/image": { "@id": "http://manu.sporny.org/images/manu.png" }

}
```

Looking at the final name-value pair (relating the profile object for 'Manu Sporny' to his chosen picture), there's quite a lot going on here ...

1) in the plain-old JSON, the link is provided as a simple URL that applications can _infer_ means that if they follow it they can find something useful
2) there are no semantics provided for the `image` name ... applications need to know somehow what it means; perhaps because the developer has read the documentation!
3) in the JSON-LD version we see that the target is an object with a name-value pair that has name of `@id`; this mechanism is used to say "here's an identified something" ... it's an explicit link
4) the `image` name is replaced by a fully qualified URL `http://schema.org/image` that, when resolved, provides you with the information about the semantics of that name.

If desired, you can also express the Type of the thing being linked to by including a name-value pair with name of `@type` in the object ...

One can also use JSON-LDs `@context` (see [2]) to make the resulting JSON look more 'normal':

```

{

  "@context":

  {

    "name": "http://schema.org/name",

    "image": {

      "@id": "http://schema.org/image",

      "@type": "@id"

    },

    "homepage": {

      "@id": "http://schema.org/url",

      "@type": "@id"

    }

  },

  "name": "Manu Sporny",

  "homepage": "http://manu.sporny.org/",

  "image": "http://manu.sporny.org/images/manu.png"

}
```

(the `@context` object can be referenced via HTTP header so the JSON document itself doesn't even need to include it)

Here we see that the name `image` has been mapped to `http://schema.org/image` and that the type of that object has been set to `@id` ... meaning that `image` will always refer to a link.

So this works for me ... but there is no general agreement how links should be done in 'plain-old' JSON.

Looking at Simon Cox's OM-JSON presentation (from the OGC TC meeting in Nottingham) he proposes using names like `href`, `rel` and `title` (etc) which (mostly) map to the properties of XLINKs [3] ... e.g.

```
{
    "id": "spec1",
    "sampledFeature": {
        "href": "http://example.org/featureA", "title": "test feature A"
    },
    "complex": [
        { "rel": "http://example.org/parent", "href": "http://example.org/sample2" },
        { "rel": "http://example.org/child", "href": "http://example.org/sample3"  }
    ],
    ...
}
```

Looking at Link-Objects [4], GeoJSON provides a different mechanism. The spec says:

A link object has one required member: "href", and one optional member: "type".

for example:

```

"crs": {

    "type": "link",

    "properties": {

      "href": "http://example.com/crs/42",

      "type": "proj4"

      }

    }
```

Part of the problem is that encodings using 'plain-old' JSON don't often bother explicitly identifying the resource that they are talking about. Looking at GeoJSON [4], for example, all that spec says about identifying this is:


·         If a feature has a commonly used identifier, that identifier should be included as a member of the feature object with the name "id".
It doesn't provide any guidance about what that identifier should be (in contrast to the web-architecture and DWBP that say use HTTP URIs to identify things). Usually in JSON, the relationships between things are asserted by the nesting of objects ... which is not always convenient or possible.

So ... is JSON a link-poor format? Perhaps the problem is that there are any number of ways to do links but none that work for everyone. The only formalised standard mechanism (that I know of) is provided by JSON-LD. Perhaps this is one of the best practices we should assert?

HTH, Jeremy

[1]: http://www.w3.org/TR/json-ld/#basic-concepts

[2]: http://www.w3.org/TR/json-ld/#the-context

[3]: http://www.w3.org/TR/xlink11/

[4]: http://geojson.org/geojson-spec.html#link-objects

[5]: http://geojson.org/geojson-spec.html#feature-objects


On Fri, 16 Oct 2015 at 07:28 Linda van den Brink <l.vandenbrink@geonovum.nl<mailto:l.vandenbrink@geonovum.nl>> wrote:
Hi all,

In the last telecon Jeremy commented on JSON, saying it is a ‘link poor format’. I’m curious as to what he meant. Is JSON-LD not supposed to solve that?

@Jeremy could you expand on this?

Linda