$30 off During Our Annual Pro Sale. View Details »

Building Meaningful APIs with JSON-LD

BigBlueHat
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.

BigBlueHat

October 16, 2019
Tweet

More Decks by BigBlueHat

Other Decks in Technology

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