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
   

   View Slide

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
   

   View Slide

3. Information
   Management
   a very brief history…of why I care
   

   View Slide

4. Vannevar
   Bush
   

   View Slide

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.
   

   View Slide

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

   View Slide

7. Sir Tim
   Berners-Lee
   

   View Slide

8. Information
   Management:
   a proposal
   circa 1989
   

   View Slide

9. View Slide

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.
    

    View Slide

11. Linked Data
    image from lod-cloud.net
    

    View Slide

12. Making
    Meaningful
    Data
    

    View Slide

13. json-ld.org
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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

    View Slide

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
    

    View Slide

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

    View Slide

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

    View Slide

22. Other people’s data
    

    View Slide

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

    View Slide

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
    

    View Slide

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

    View Slide

26. Knowing from the
    Knowledge Graph
    

    View Slide

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

    View Slide

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
    

    View Slide

29. Thanks!
    bigbluehat.com
    GitHub | Twitter
    

    View Slide