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.

Transcript

1. Building Meaningful APIs with JSON-LD
2. 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
3. Information Management a very brief history…of why I care
4. Vannevar Bush
5. 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.
6. The Mechanical Encyclopedia Invented by Angela Ruiz Robles in 1949 A “read only” memex
7. Sir Tim Berners-Lee
8. Information Management: a proposal circa 1989
10. 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.
11. Linked Data image from lod-cloud.net
12. Making Meaningful Data
13. json-ld.org
14. 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
15. 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
16. 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
17. 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
18. Let’s look at how Adding context to your JSON via the JSON-LD's @context
19. @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
20. 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"}] }]
21. 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" .
22. Other people’s data
23. 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" }
24. 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
25. 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" .
26. Knowing from the Knowledge Graph
27. 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?”
28. 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
29. Thanks! bigbluehat.com GitHub | Twitter