Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Building Meaningful APIs with JSON-LD

October 16, 2019

Building Meaningful APIs with JSON-LD

Everybody loves JSON! However, JSON by itself is pretty meaningless. Well. It has meaning, but only to the original creator of that format. Developers attempt to share any defined meaning via application documentation, usage within code, or even person-to-person conversations. Often all of those exist in places far removed from the JSON document itself. Enter Linked Data. JSON-LD or "JSON for Linked Data" provides a means to connect the terminology in your idiosyncratic JSON documents to world-wide meaning via context files and URLs.


October 16, 2019

More Decks by BigBlueHat

Other Decks in Technology


  1. Hi • aka BigBlueHat • Strategic Architect at John Wiley

    & Sons, Inc. • Co-Organizer of REST Fest • Co-Editor of the W3C Web Annotation Data Model & Vocabulary • Co-Chair of the W3C JSON-LD Working Group • Contributor to the W3C Web Publishing Working Group • Core Committer to Apache Annotator & Apache CouchDB
  2. Memex – circa 1945 • “We seem to be worse

    off than before — for we can enormously extend the record; yet even in its present bulk we can hardly consult it.” • “One cannot hope thus to equal the speed and flexibility with which the mind follows an associative trail, but it should be possible to beat the mind decisively in regard to the permanence and clarity of the items resurrected from storage.” • Wholly new forms of encyclopedias will appear, ready made with a mesh of associative trails running through them, ready to be dropped into the memex and there amplified.
  3. Four rules of Linked Data • Use URIs as names

    for things. • Use HTTP URIs so that people can look up those names. • When someone looks up a URI, provide useful information, using the standard formats. • Include links to other URIs so that they can discover more things.
  4. Typical JSON document { "name": "John Lennon", "born": "1940-10-09", "spouse":

    “Cynthia Lennon" } • Computer sees strings • English speakers can guess meaning from keys and values • Non-English speakers have no route to documentation • Document has no identity • Document has no connection to other documents
  5. How about Hypermedia { "name": "John Lennon", "born": "1940-10-09", "spouse":

    "Cynthia Lennon", "_links": { "self": "http://example.com/john_lennon", "next": "http://example.com/ringo", "up": "http://example.com/the_beetles" } • Computer still sees strings • English speakers can guess meaning from keys and values • Non-English speakers have no route to documentation • Document does have identity • Document does have connection to other documents
  6. Adding Meaning with JSON-LD { "@context": "https://json-ld.org/contexts/person.jsonld", "@id": "http://dbpedia.org/resource/John_Lennon", "name":

    "John Lennon", "born": "1940-10-09", "spouse": "http://dbpedia.org/resource/Cynthia_Lennon“ } • Computer sees strings, URLs, and a date • English speakers can get URLs for every term (probably) with documentation • Non-English speakers may discover documentation in their language • Document has clear identity • Document connects to other documents
  7. By Our Powers Combined! { "@context": "https://json-ld.org/contexts/person.jsonld", "@id": "http://dbpedia.org/resource/John_Lennon", "name":

    "John Lennon", "born": "1940-10-09", "spouse": "http://dbpedia.org/resource/Cynthia_Lennon", "_links": { "self": "http://dbpedia.org/resource/John_Lennon" } } • Adds hypermedia affordances for UX and bots looking to browse around collections • More specifications exist (Hydra, Web of Things) that expand on this possibility
  8. @context { "@context": { "name": "http://xmlns.com/foaf/0.1/name", "born": { "@id": "http://schema.org/birthDate",

    "@type": "http://www.w3.org/2001/XMLSchema#date" }, "spouse": { "@id": "http://schema.org/spouse", "@type": "@id" } } } https://json-ld.org/contexts/person.jsonld
  9. Expanded form [ {"@id": "http://dbpedia.org/resource/John_Lennon", "http://schema.org/birthDate": [ { "@type": "http://www.w3.org/2001/XMLSchema#date",

    “@value": "1940-10-09"}], "http://xmlns.com/foaf/0.1/name": [ {"@value": "John Lennon"}], "http://schema.org/spouse": [ {"@id": "http://dbpedia.org/resource/Cynthia_Lennon"}] }]
  10. Triples – Subject, Predicate, Object <http://dbpedia.org/resource/John_Lennon> <http://schema.org/birthDate> "1940-10-09"^^<http://www.w3.org/2001/XMLSchema#date> . <http://dbpedia.org/resource/John_Lennon>

    <http://schema.org/spouse> <http://dbpedia.org/resource/Cynthia_Lennon> . <http://dbpedia.org/resource/John_Lennon> <http://xmlns.com/foaf/0.1/name> "John Lennon" .
  11. Reading Somebody Else’s JSON { "@context": "https://example.com/person.jsonld", "@id": "http://dbpedia.org/resource/John_Lennon", "personName":

    "John Lennon", "bornOn": "1940-10-09", "marriedTo": "http://dbpedia.org/resource/Cynthia_Lennon" }
  12. Their @context { "@context": { "personName": "http://xmlns.com/foaf/0.1/name", "bornOn": { "@id":

    "http://schema.org/birthDate", "@type": "http://www.w3.org/2001/XMLSchema#date" }, "marriedTo": { "@id": "http://schema.org/spouse", "@type": "@id" } } } http://example.com/person.jsonld
  13. Triples – Subject, Predicate, Object <http://dbpedia.org/resource/John_Lennon> <http://schema.org/birthDate> "1940-10-09"^^<http://www.w3.org/2001/XMLSchema#date> . <http://dbpedia.org/resource/John_Lennon>

    <http://schema.org/spouse> <http://dbpedia.org/resource/Cynthia_Lennon> . <http://dbpedia.org/resource/John_Lennon> <http://xmlns.com/foaf/0.1/name> "John Lennon" .
  14. Knowledge Graphs • Can store any Linked Data triples 

    Even data your application my not (yet) understand • Can be used to answer interesting questions  “Who else was married to John Lennon?” • Allows querying across the entire graph and mixing output results  “What world events happened the year John Lennon was born?”  “What was John’s first song after marrying Yoko Ono?”
  15. Projects to Watch • W3C Web of Things Working Group

     Combines JSON-LD and JSON Schema + Hypermedia affordances  Allowing cross-product sensor output understanding across meaningful IoT data • LevelGraph  JavaScript-based knowledge graph  Playground that supports JSON-LD, Turtle, and other Linked Data formats • JSON-LD Community Group  Long running W3C Community Group focused on exploring and implementing JSON-LD