ld-query

A tiny lib to assist in the querying of (expanded) JSON-LD documents. The library uses ES5-compatible code, so you can run it on older browsers or servers without needing to transpile it.

tl;dr: Examples

The JSON-LD format is defined in the W3C JSON-LD recommendation.

An example of a JSON-LD document:

{
  "@context": {
    "@vocab": "http://schema.org/",
    "note-to-self": "http://www.example.org#note-to-self",
    "firstName": "http://xmlns.com/foaf/0.1/firstName",
    "accountName": "http://xmlns.com/foaf/0.1/accountName",
    "favouriteReads": {
      "@id": "http://www.example.org#favouriteReads",
      "@container": "@index"
    }
  },
  "@type": "Person",
  "description": "Linked person",
  "favouriteReads": {
    "banks-exc": {
      "@id": "http://www.isbnsearch.org/isbn/9780553575378",
      "@type": "Book",
      "author": "Iain M Banks",
      "name": "Excession"
    },
    "pynchon-gr": {
      "@id": "http://www.isbnsearch.org/isbn/9780143039945",
      "@type": [ "Book", "Movie" ],
      "author": "Thomas Pynchon",
      "name": "Gravity's Rainbow",
      "note-to-self": "Need to finish reading this"
    }
  },
  "accountName": "goofballLogic",
  "firstName": "Andrew",
  "name": "Andrew Goofball"
}

Expansion is a pre-requisite

WTF? Why would I do this to my data? Here's a video explaining the mechanism, which goes some way in justifying what we're doing here.

In addition, we feel that the compaction algorithm isn't completely dependable when you're not sure what data documents you are merging together, so it feels "safer" to process the expanded form.

This library aims to assist with querying json-ld documents in their expanded form. It is worth noting that although the JSON-LD expansion algorithm is defined in the JSON-LD Processing Algorithms and API recommendation, there's no implementation of the expansion algorithm in this library.

To use this library, your data needs to be in exapnded form. You can use existing implementations of the expansion API to achieve this. For example, jsonld.js is a fairly mature implementation of the standard.

An example of an expanded JSON-LD document:

[
  {
    "@type": [
      "http://schema.org/Person"
    ],
    "http://schema.org/description": [
      {
        "@value": "Linked person"
      }
    ],
    "http://www.example.org#favouriteReads": [
      {
        "@id": "http://www.isbnsearch.org/isbn/9780553575378",
        "@type": [
          "http://schema.org/Book"
        ],
        "@index": "banks-exc",
        "http://schema.org/author": [
          {
            "@value": "Iain M Banks"
          }
        ],
        "http://schema.org/name": [
          {
            "@value": "Excession"
          }
        ]
      },
      {
        "@id": "http://www.isbnsearch.org/isbn/9780143039945",
        "@type": [
          "http://schema.org/Book",
          "http://schema.org/Movie"
        ],
        "@index": "pynchon-gr",
        "http://schema.org/author": [
          {
            "@value": "Thomas Pynchon"
          }
        ],
        "http://schema.org/name": [
          {
            "@value": "Gravity's Rainbow"
          }
        ],
        "http://www.example.org#note-to-self": [
          {
            "@value": "Need to finish reading this"
          }
        ]
      }
    ],
    "http://xmlns.com/foaf/0.1/accountName": [
      {
        "@value": "goofballLogic"
      }
    ],
    "http://xmlns.com/foaf/0.1/firstName": [
      {
        "@value": "Andrew"
      }
    ],
    "http://schema.org/name": [
      {
        "@value": "Andrew Goofball"
      }
    ],
    "http://www.example.org#friendCount": [
      {
        "@value": 0
      }
    ]
  }
]

Structure

We are trying to implement functionality which follows where possible the definition established by the DOM querySelector and DOM querySelectorAll APIs. Because the definitions will only ever by analogous to each other, we use "query" and "queryAll" rather than "querySelector" and "querySelectorAll".

Examples

We would like to be able to query the data in a fairly simple manner, like this:

Start by creating the ld-query object:

var context = LD( {
  "@vocab": "http://www.schema.org/",
  "foaf": "http://xmlns.com/foaf/0.1/",
  "ex": "http://www.example.org#",
  "isbn": "http://www.isbnsearch.org/isbn/"
} );

var doc = context( data );

or

var doc = LD( data, {
   "@vocab": "http://www.schema.org/",
   "foaf": "http://xmlns.com/foaf/0.1/",
   "ex": "http://www.example.org#",
   "isbn": "http://www.isbnsearch.org/isbn/"
} );

The resulting object can be queried for the properties we need:

doc.query("foaf:firstName");                                      // QueryNode object
doc.query("foaf:firstName @value");                               // "Andrew"

doc.query("description @value");                                  // "Linked person"
doc.query("@value");                                              // "goofballLogic"

doc.query("ex:friendCount @value");                               // 0

doc.query("ex:favouriteReads");                                   // QueryNode object
doc.query("ex:favouriteReads").query("author @value")             // "Iain M Banks"
doc.query("ex:favouriteReads author @value");                     // "Iain M Banks"
doc.query("author @value")                                        // "Iain M Banks"
doc.query("ex:favouriteReads @value");                            // "Iain M Banks"

doc.query("ex:favouriteReads author").json();                     // { "http://schema.org/author": [ { "@value": "Iain M Banks" } ], http://schema.org/name": [ { "@value": "Excession" } ], "@index": "banks-exc" }

doc.queryAll("ex:favouriteReads author");                         // array of 2 QueryNode objects
doc.queryAll("ex:favouriteReads author @value");                  // [ "Iain M Banks", "Thomas Pynchon" ]
doc.queryAll("ex:favouriteReads").length;                         // 1

doc.queryAll("ex:favouriteReads")[0]                              // QueryNode object

doc.queryAll("firstName @value");                                 // [ "Andrew" ]
doc.queryAll("firstName").length;                                 // 1

doc.query("firstName").length;                                    // 1

doc.query("somepropertynotinyourdocument");                       // null
doc.query("somepropertynotinyourdocument @value")                 // null

doc.queryAll("somepropertynotinyourdocument @value")              // []

doc.query("ex:favouriteReads[@index=pynchon_gp] name @value")     // "Gravity's Rainbow"

doc.query("*[@id=isbn:9780143039945] name @value")                // "Gravity's Rainbow"
doc.query("[@id=isbn:9780143039945] name @value")                 // "Gravity's Rainbow"
doc.query("#isbn:9780143039945 name @value")                      // "Gravity's Rainbow"

doc.queryAll("ex:favouriteReads @index")                          // [ "banks-exc", "pynchon-gr" ]
doc.query("ex:favouriteReads @id")                                // [ "http://www.isbnsearch.org/isbn/9780553575378" ]

doc.queryAll("name @value")                                       // [ "Excession", "Gravity's Rainbox", "Andrew Goofball" ]
doc.queryAll("> name @value")                                     // [ "Andrew Goofball" ]
doc.queryAll("ex:favouriteReads > name @value")                   // [ "Excession", "Gravity's Rainbox" ]

doc.query("@type")                                               // [ "http://schema.org/Person" ]
doc.queryAll("@type")                                            // [ [ "http://schema.org/Person"], [ "http://schema.org/Book" ], [ "http://schema.org/Book", "http://schema.org/Movie" ] ]

Benchmarking

Note: The benchmarking tools require that you have git available on the path.

To benchmark the current version of the library against the latest commit to the master branch, run:

npm run benchmark

To benchmark the current version of the library against a particular commit, branch or tag, run:

npm run benchmark -- --compare-to <commit|branch|tag>

To run only a subset of benchmarks, run:

npm run benchmark -- --benchmark "<regexp matching benchmark names>"