JSON-LD API Failground

This web site is designed to show the fatal flaw of JSON-LD usage for API specs. The core problem with JSON-LD is that there are an infinite number of legitimate serializations for any JSON-LD document. As such it is more costly to parse an incoming JSON-LD document than a simple JSON document with predictable data elements.

I really like JSON-LD for lots of things - it is a very elegant specification for representing data where the data model is continuously expanding and evolving. It surpasses any previous Semantic Web or XML representation for this use case. My only quarrel is that unconstrained JSON-LD is completely unsuitable for API specifications where performance matters. Perhaps at some point in the future unconstrained JSON-LD won't be a performance handicap for scalable APIs - but for now, we must build best practices around JSON-LD for APIs that makes it possible to parse data using only JSON libraries or not use JSON-LD at all for API work.

To demonstrate the issue of "infinite number of legitimate serializations", every time this web site is visited or auto-refreshed every 5 seconds, we will generate yet another completely legitimate JSON-LD serialization for the same JSON. We use the "library" example JSON-LD from the JSON Playground and the PHP JSON-Library written by Manu Sporny.

{
    "@context": {
        "txj35SoWeG": "http:\/\/purl.org\/dc\/elements\/1.1\/",
        "8kH1BY6cFL": "http:\/\/example.org\/vocab#",
        "xsd": "http:\/\/www.w3.org\/2001\/XMLSchema#",
        "ex:contains": {
            "@type": "@id"
        }
    },
    "@graph": [
        {
            "@id": "http:\/\/example.org\/library",
            "@type": "8kH1BY6cFL:Library",
            "8kH1BY6cFL:contains": {
                "@id": "http:\/\/example.org\/library\/the-republic"
            }
        },
        {
            "@id": "http:\/\/example.org\/library\/the-republic",
            "@type": "8kH1BY6cFL:Book",
            "8kH1BY6cFL:contains": {
                "@id": "http:\/\/example.org\/library\/the-republic#introduction"
            },
            "txj35SoWeG:creator": "Plato",
            "txj35SoWeG:title": "The Republic"
        },
        {
            "@id": "http:\/\/example.org\/library\/the-republic#introduction",
            "@type": "8kH1BY6cFL:Chapter",
            "txj35SoWeG:description": "An introductory chapter on The Republic.",
            "txj35SoWeG:title": "The Introduction"
        }
    ]
}

Original JSON:

{
  "@context": {
    "dc": "http://purl.org/dc/elements/1.1/",
    "ex": "http://example.org/vocab#",
    "xsd": "http://www.w3.org/2001/XMLSchema#",
    "ex:contains": {
      "@type": "@id"
    }
  },
  "@graph": [
    {
      "@id": "http://example.org/library",
      "@type": "ex:Library",
      "ex:contains": "http://example.org/library/the-republic"
    },
    {
      "@id": "http://example.org/library/the-republic",
      "@type": "ex:Book",
      "dc:creator": "Plato",
      "dc:title": "The Republic",
      "ex:contains": "http://example.org/library/the-republic#introduction"
    },
    {
      "@id": "http://example.org/library/the-republic#introduction",
      "@type": "ex:Chapter",
      "dc:description": "An introductory chapter on The Republic.",
      "dc:title": "The Introduction"
    }
  ]
}