Building Meaningful APIs with JSON-LD 

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 

Information Management a very brief history…of why I care 

Vannevar Bush 

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. 

The Mechanical Encyclopedia Invented by Angela Ruiz Robles in 1949 A “read only” memex 

Sir Tim Berners-Lee 

Information Management: a proposal circa 1989 

No content

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. 

Linked Data image from lod-cloud.net 

Making Meaningful Data 

json-ld.org 

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 

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 

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 

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 

Let’s look at how Adding context to your JSON via the JSON-LD's @context 

@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 

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"}] }] 

Triples – Subject, Predicate, Object "1940-10-09"^^ . . "John Lennon" . 

Other people’s data 

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" } 

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 

Triples – Subject, Predicate, Object "1940-10-09"^^ . . "John Lennon" . 

Knowing from the Knowledge Graph 

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?” 

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 

Thanks! bigbluehat.com GitHub | Twitter