Coder Social home page Coder Social logo

ld-query's Introduction

Build Status

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

ld-query's People

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar

ld-query's Issues

Attribute matching doesn't handle arrays

I've noticed that attributes can be arrays e.g.

"@type": [
    "http://www.example.org#deleteOperation",
    "http://www.w3.org/ns/hydra/core#DeleteResourceOperation"
]

The current matching does not handle this.

Accept @vocab as part of the context

If we specify @vocab as part of the json-ld context, querying for bare property names should then be interpreted as belonging to the @vocab.

e.g. if the context is

{
    "@vocab": "http://www.example.org#"
}

then a query for "name @value" should be interpreted as targetting:

{
    "http://www.example.org#name": [ { "@value": "gabrisha" } ]
}

[@attribute=value] does not appear to work with regular strings as value

The document I'm querying is Example 2 from http://schema.org/Book.
Here's a relevant snippet:

{
  "@context": "http://schema.org",
  "@graph": [
    {
      "@id": "#author",
      "@type": "Person",
      "birthDate": "1892",
      "deathDate": "1973",
      "name": "Tolkien, J. R. R. (John Ronald Reuel)",
      "sameAs": "http://viaf.org/viaf/95218067"
    }]
}

Here is my query:

const doc = LD({
    "@vocab": "http://schema.org/",
})(expanded)
expect(doc.query("[name=Tolkien, J. R. R. (John Ronald Reuel)]")).to.exist

This returns null, whereas I expect it to return the author's node.

Am I misunderstanding how the [@attribute=value] code is supposed to work? I'd like to be able to query on matching values within the document, not just on document structure. Is this supported?

Internally, I see your extractStep function is calling expand on step.value because it doesn't match the nonExpandableValuePropNamePattern. We end up with the value http://schema.org/Return of the King.

If I comment out the call to expand the query still fails to match, so there's something else going on as well.

Simplifying processing of array elements

For the same document in the README.md, how would I go about mapping the entries under favouriteReads to my own document model?

At the moment I would have to do

var favs = doc.query("ex:favouriteReads"); // query for favouriteReads
if ( favs ) {  // check it isn't null
  model = favs.json() // get the array
    .map( x => ldQuery( x ) ) // map each aray entry to a new query object
    .map( x=> ( { // query again to create my own document model
      author: x.query( "so:author @value" ),
      title: x.query( "so:name @value" )
    } ) );
}

Is there a shorter way to do this?
I guess one way could be that if you use 'queryAll' against a path ("ex:favouriteReads") that points to an array that you get each entry of the array as a QueryNode? Or might that lead to confusing use cases?

The other option would be wildcards e.g.

model = doc.queryAll("ex:favouriteReads > *") // query for all children of favouriteReads
// since queryAll returns either an empty array or an array of queryNodes
// you can skip the safety check and go directly to mapping
    .map( x=> ( { 
      author: x.query( "so:author @value" ),
      title: x.query( "so:name @value" )
    } ) );

What do you think?

Querying for a @value of 0 returns a null

if I query a document

[ {
   "http://example.org#name" : [ { "@value" : "Gwyneth" } ],
   "http://example.org#age" : [ { "@value" : 0 } ]
} ]

using

const age = doc.query( "ex:age @value" );

it returns a null, when I expect a 0

Empty context causes error

If you pass in {} as the context, you get an error:

TypeError: expand is not a function
    at extractStep (/home/ubuntu/workspace/node_modules/ld-query/src/ld-query.js:284:29)
    at getSteps (/home/ubuntu/workspace/node_modules/ld-query/src/ld-query.js:296:25)
    at select (/home/ubuntu/workspace/node_modules/ld-query/src/ld-query.js:326:21)
    at QueryNode.query (/home/ubuntu/workspace/node_modules/ld-query/src/ld-query.js:351:25)

Documentation mentions a constructor pattern that doesn't work

The README.md mentions two constructor patterns

var context = LD( { ... etc. } );
var doc = context( data );

or

var doc = LD( data, { ... context ... } );

only the latter actually works. The former gives a 'Cannot convert undefined or null to object' error

Add examples

Some examples of using the library:

  1. Client-side javascript
  2. node.js

Precedence of result from 'query'

Given a document that includes

[
  {
    ...,
    "http://example.org#annotations": [
      {
        "@type": [
          "https://www.w3.org/TR/annotation-model/Annotation"
        ],
        "https://www.w3.org/TR/annotation-model/body": [
          {
            ...,
            "http://example.org#identifier": [
              {
                "@value": "annotation1_identifier"
              }
            ]
          }
        ],
      },
    ],
    "http://example.org#identifier": [
      {
        "@value": "12345"
      }
    ],
  }
]

what should we expect query( "ex:identifier" ) to return? The "annotation1_identifier" or "12345"? At the moment it is "annotation1_identifier", the first entry that matches the query.

If this was html e.g.

<div class="b">
  <div class="b">
    <div class="a">test1</div>
  </div>
</div>
<div class="a">test2</div>

then document.querySelector(".a").innerHTML returns "test1", so that matches the functionality of the ld-query 'query' method

To get 'test2' in the html we'd need to use document.querySelector( "body > .a" )

Does ld-query need changed to find the 'simplest' match for a path? Or does it need to include additional operator types like '>'? Or can the 'expand' method that it uses internally be externalised, so that developers can process json manually (though that's a bit of a fudge)?

Should @type be "final"

Currently, if you query for @id, @value or @Index, you get the literal value back, rather than a QueryNode(s). Currently querying for @type returns QueryNode - shouldn't it also return the value instead? If there's more than one @type, an array of the literal values could be returned.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.