<commit_before>[![Build Status](https://travis-ci.org/goofballLogic/ld-query.svg?branch=master)](https://travis-ci.org/goofballLogic/ld-query)

# ld-query

A tiny lib to assist in the querying of (expanded) JSON-LD documents.

tl;dr: [Examples](#examples)

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

An example of a JSON-LD document:

```
{
  "@context": {
    "so": "http://schema.org/",
    "foaf": "http://xmlns.com/foaf/0.1/",
    "name": "so:name",
    "description": "so:description",
    "author": "so:author",
    "firstName": "foaf:firstName",
    "accountName": "foaf:accountName",
    "favouriteReads": {
      "@id": "http://www.example.org#favouriteReads",
      "@container": "@index"
    }
  },
  "@type": "so:Person",
  "firstName": "Andrew",
  "accountName": "<EMAIL>",
  "description": "Linked person",
  "favouriteReads": {
    "banks-exc": {
      "author": "<NAME>",
      "name": "Excession"
    },
    "pynchon-gr": {
      "author": "<NAME>",
      "name": "<NAME>"
    }
  }
}
```

##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://xmlns.com/foaf/0.1/accountName": [
      {
        "@value": "goofballLogic"
      }
    ],
    "http://schema.org/description": [
      {
        "@value": "Linked person"
      }
    ],
    "http://www.example.org#favouriteReads": [
      {
        "http://schema.org/author": [
          {
            "@value": "<NAME>"
          }
        ],
        "http://schema.org/name": [
          {
            "@value": "Excession"
          }
        ],
        "@index": "banks-exc"
      },
      {
        "http://schema.org/author": [
          {
            "@value": "<NAME>"
          }
        ],
        "http://schema.org/name": [
          {
            "@value": "Gravity's Rainbow"
          }
        ],
        "@index": "pynchon-gr"
      }
    ],
    "http://xmlns.com/foaf/0.1/firstName": [
      {
        "@value": "Andrew"
      }
    ]
  }
]
```

##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( {
  "so": "http://www.schema.org/",
  "foaf": "http://xmlns.com/foaf/0.1/",
  "ex": "http://www.example.org#"
} );

var doc = context( data );
```

or
```
var doc = LD( data, {
   "so": "http://www.schema.org/",
   "foaf": "http://xmlns.com/foaf/0.1/",
   "ex": "http://www.example.org#"
} );
```

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("so:description @value");                               // "Linked person"
doc.query("@value");                                              // "goofballLogic"

doc.query("ex:favouriteReads");                                   // QueryNode object
doc.query("ex:favouriteReads").query("so:author @value")          // "<NAME>"
doc.query("ex:favouriteReads so:author @value");                  // "<NAME>"
doc.query("so:author @value")                                     // "<NAME>"
doc.query("ex:favouriteReads @value");                            // "<NAME>"

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

doc.queryAll("ex:favouriteReads so:author");                      // array of QueryNode objects
doc.queryAll("ex:favouriteReads so:author @value");               // [ "<NAME>", "<NAME>" ]
doc.queryAll("ex:favouriteReads").length;                         // 2

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

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

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

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

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

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

[W3C JSON-LD recommendation]: https://www.w3.org/TR/json-ld/
[JSON-LD Processing Algorithms and API recommendation]: https://www.w3.org/TR/json-ld-api/#expansion
[jsonld.js]: https://github.com/digitalbazaar/jsonld.js
[a video explaining]: https://www.youtube.com/watch?v=Tm3fD89dqRE
[DOM querySelector]: https://www.w3.org/TR/selectors-api2/#queryselector
[DOM querySelectorAll]: https://www.w3.org/TR/selectors-api2/#queryselectorall
<commit_msg>corrected docs<commit_after>[![Build Status](https://travis-ci.org/goofballLogic/ld-query.svg?branch=master)](https://travis-ci.org/goofballLogic/ld-query)

# ld-query

A tiny lib to assist in the querying of (expanded) JSON-LD documents.

tl;dr: [Examples](#examples)

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

An example of a JSON-LD document:

```
{
  "@context": {
    "so": "http://schema.org/",
    "foaf": "http://xmlns.com/foaf/0.1/",
    "name": "so:name",
    "description": "so:description",
    "author": "so:author",
    "firstName": "foaf:firstName",
    "accountName": "foaf:accountName",
    "favouriteReads": {
      "@id": "http://www.example.org#favouriteReads",
      "@container": "@index"
    }
  },
  "@type": "so:Person",
  "firstName": "Andrew",
  "accountName": "goofballLogic",
  "description": "Linked person",
  "favouriteReads": {
    "banks-exc": {
      "author": "<NAME>",
      "name": "Excession"
    },
    "pynchon-gr": {
      "author": "<NAME>",
      "name": "Gravity's Rainbow"
    }
  }
}
```

##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://xmlns.com/foaf/0.1/accountName": [
      {
        "@value": "goofballLogic"
      }
    ],
    "http://schema.org/description": [
      {
        "@value": "Linked person"
      }
    ],
    "http://www.example.org#favouriteReads": [
      {
        "http://schema.org/author": [
          {
            "@value": "<NAME>"
          }
        ],
        "http://schema.org/name": [
          {
            "@value": "Excession"
          }
        ],
        "@index": "banks-exc"
      },
      {
        "http://schema.org/author": [
          {
            "@value": "<NAME>"
          }
        ],
        "http://schema.org/name": [
          {
            "@value": "Gravity's Rainbow"
          }
        ],
        "@index": "pynchon-gr"
      }
    ],
    "http://xmlns.com/foaf/0.1/firstName": [
      {
        "@value": "Andrew"
      }
    ]
  }
]
```

##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( {
  "so": "http://www.schema.org/",
  "foaf": "http://xmlns.com/foaf/0.1/",
  "ex": "http://www.example.org#"
} );

var doc = context( data );
```

or
```
var doc = LD( data, {
   "so": "http://www.schema.org/",
   "foaf": "http://xmlns.com/foaf/0.1/",
   "ex": "http://www.example.org#"
} );
```

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("so:description @value");                               // "Linked person"
doc.query("@value");                                              // "goofballLogic"

doc.query("ex:favouriteReads");                                   // QueryNode object
doc.query("ex:favouriteReads").query("so:author @value")          // "<NAME>"
doc.query("ex:favouriteReads so:author @value");                  // "<NAME>"
doc.query("so:author @value")                                     // "<NAME>"
doc.query("ex:favouriteReads @value");                            // "<NAME>"

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

doc.queryAll("ex:favouriteReads so:author");                      // array of 2 QueryNode objects
doc.queryAll("ex:favouriteReads so:author @value");               // [ "<NAME>", "<NAME>" ]
doc.queryAll("ex:favouriteReads").length;                         // 1

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

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

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

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

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

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

[W3C JSON-LD recommendation]: https://www.w3.org/TR/json-ld/
[JSON-LD Processing Algorithms and API recommendation]: https://www.w3.org/TR/json-ld-api/#expansion
[jsonld.js]: https://github.com/digitalbazaar/jsonld.js
[a video explaining]: https://www.youtube.com/watch?v=Tm3fD89dqRE
[DOM querySelector]: https://www.w3.org/TR/selectors-api2/#queryselector
[DOM querySelectorAll]: https://www.w3.org/TR/selectors-api2/#queryselectorall

{'fraction_non_alphanumeric': 0.16247310048005298, 'fraction_numerical': 0.004221155437841417, 'mean_word_length': 2.32681718061674, 'pattern_counts': {'":': 102, '<': 27, '<?xml version=': 0, '>': 33, 'https://': 16, 'lorem ipsum': 0, 'www.': 22, 'xml': 10}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 22, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1102988', 'n_tokens_mistral': 3857, 'n_tokens_neox': 3734, 'n_words': 895}