lanthaler / jsonld Goto Github PK

JSON-LD processor for PHP

License: MIT License

PHP 99.62% Dockerfile 0.38%

json-ld php linked-data semantic-web schema-org web-api rest hypermedia

jsonld's Introduction

JsonLD

JsonLD is a fully conforming JSON-LD processor written in PHP. It is extensively tested and passes the official JSON-LD test suite.

There's an online playground where you can evaluate the processor's basic functionality.

Additionally to the features defined by the JSON-LD API specification, JsonLD supports framing (including value matching, deep-filtering, aggressive re-embedding, and named graphs) and an experimental object-oriented interface for JSON-LD documents.

Installation

The easiest way to install JsonLD is by requiring it with Composer.

composer require ml/json-ld

... and including Composer's autoloader to your project

require('vendor/autoload.php');

Of course, you can also download JsonLD as ZIP archive from Github.

JsonLD requires PHP 5.3 or later.

Usage

The library supports the official JSON-LD API as well as a object-oriented interface for JSON-LD documents (not fully implemented yet, see issue #15 for details).

All classes are extensively documented. Please have a look at the source code.

// Official JSON-LD API
$expanded = JsonLD::expand('document.jsonld');
$compacted = JsonLD::compact('document.jsonld', 'context.jsonld');
$framed = JsonLD::frame('document.jsonld', 'frame.jsonld');
$flattened = JsonLD::flatten('document.jsonld');
$quads = JsonLD::toRdf('document.jsonld');

// Output the expanded document (pretty print)
print JsonLD::toString($expanded, true);

// Serialize the quads as N-Quads
$nquads = new NQuads();
$serialized = $nquads->serialize($quads);
print $serialized;

// And parse them again to a JSON-LD document
$quads = $nquads->parse($serialized);
$document = JsonLD::fromRdf($quads);

print JsonLD::toString($document, true);

// Node-centric API
$doc = JsonLD::getDocument('document.jsonld');

// get the default graph
$graph = $doc->getGraph();

// get all nodes in the graph
$nodes = $graph->getNodes();

// retrieve a node by ID
$node = $graph->getNode('http://example.com/node1');

// get a property
$node->getProperty('http://example.com/vocab/name');

// add a new blank node to the graph
$newNode = $graph->createNode();

// link the new blank node to the existing node
$node->addPropertyValue('http://example.com/vocab/link', $newNode);

// even reverse properties are supported; this returns $newNode
$node->getReverseProperty('http://example.com/vocab/link');

// serialize the graph and convert it to a string
$serialized = JsonLD::toString($graph->toJsonLd());

Commercial Support

Commercial support is available on request.

jsonld's People

Contributors

Stargazers

Watchers

jsonld's Issues

Type coercion to @id doesn't work with @vocab

Example:

{
  "@context": {
    "@vocab": "http://xmlns.com/foaf/0.1/",
    "homepage": {
      "@type": "@id"
    }
  },
  "name": "Markus Lanthaler",
  "homepage": "http://www.markus-lanthaler.com/"
}

Base toRDF on node map

Currently the triples are generated directly from expanded output.

Add required PHP-Version in Readme

In production settings, restrictions re. the installed PHP version are quite frequent. Therefore, it would be great to see the required PHP (sub-) version on the readme page.

Add option to not automatically retrieve remote contexts

Add an option to all operations not automatically retrieve remote contexts

Add support for reverse properties in framing

Add support for the compactArrays flag

See json-ld/json-ld.org#122 for details

Detect recursive context imports

An external context A might include an external context B which in turn again includes context A. This should be detected and trigger an error.

Handle HTTP redirects properly

... which means the documents base URL has to be updated.

If "@type": "@vocab" is specified for a term in the active context, then processing for the value associated with the term attempts to resolve it as an IRI - first processing it as a term, then a CURIE, then an absolute IRI, then against the active @vocab (if present), then a document-relative IRI.

The value space of values coerced to @id is: compact IRI, absolute IRI, relative IRI.

[http://json-ld.org/minutes/2013-02-12/#resolution-3]

Make sure inputs are never modified

Add support for @vocab

Invalid value for @language error

While playing with the Hydra Console I came across this issue, which looks like a bug in your JSON-LD processor:

PHP Fatal error:  Uncaught exception 'ML\JsonLD\Exception\SyntaxException'
with message 'Invalid value for @language detected (must be a string) (near 
{"@language":{"__iri":"@language","__value":"ja"},"@value":
{"__iri":"@value","__value":"リズム天国ゴールド"}}).'

The original document does have just a string "ja" as value for @language, so it seems the processor is complaining about an expansion it performed itself.

I've uploaded a testcase which shows the problem using your HydraConsole proxy:

http://www.markus-lanthaler.com/hydra/console/proxy.php?debug=true&url=https://frob.nl/tmp/jsonld-language-bug/gmb.jsonld

Parse documents into interlinked object structures

It should be possible to work directly with the data contained in a document. Some functionality that should be supported:

// load a document
$doc = Document::load('document.jsonld');

// get the default graph
$graph = $doc->getGraph();

// get all nodes in the document
$nodes = $graph->getNodes();

// retrieve a node by ID
$node = $graph->getNode('http://example.com/node1');

// get a property
$node->getProperty('http://example.com/vocab/name');

// add a new blank node to the document
$newNode = $graph->createNode();

// link the new blank node to the existing node
$node->addPropertyValue('http://example.com/vocab/link', $newNode);

// even reverse properties are supported; this returns $newNode
$node->getReverseProperty('http://example.com/vocab/link');

At a later point, it should also be possible to query for nodes or properties.

Drop keywords such as @container from body as they aren't allowed there

PSR-1 and PSR-2 compliancy

The coding style should be changed to comply with PSR-1 and PSR-2.

Update error handling

... to be more in line with the official error handling mechansim. This doesn't mean that callbacks should be used but that the error constants should be the same (and they should be thrown under the same circumstances).

Implement conversion from RDF

Bugs with handling @base: null

Using the playground for the JsonLD processor, @base: null causes some problems when @id is set to the empty string. See: http://tinyurl.com/npjymy9

If you look at the compacted tab, the @id should be changed to ./, and if you look at the flatten or toRDF tabs, you get an error.

This is related to PHP's problems with empty string keys, but I'm sure it's fixable as php-json-ld produces the same (and correct) output as jsonld.js with the above input.

Add support for JsonLdOptions

See http://json-ld.org/spec/latest/json-ld-api/#jsonldoptions for details. This also means that the base IRI parameter is move into the generic options parameter.

Handle HTTP Link header

See http://www.w3.org/TR/json-ld/#interpreting-json-as-json-ld

Undocumented dependency for regex parsing in IRI.php?

The parse function of IRI.php works fine for me on a Centos 6/PHP 5.3.3 installation. It fails however on Centos 5 (with rpm package php53 (PHP 5.3.3) installed).

I could track it down to to following lines of code:

[^:/?#]+):)?' . '((?P//)(?P[^/?#]*))?(?P[^?#]*)' . '((?\?)(?P[^#]*))?(#(?P.*))?|'; preg_match($regex, $iri, $match); print $match['scheme'] . "\n"; ``` On Centos 6, "http" is printed. On Centos 5, I get the message PHP Warning: preg_match(): Compilation failed: unrecognized character after (?< at offset 89 in /opt/thes/var/stw-ws/temp.php on line 9 without any other output.

Change coding style

Change coding style to PSR-2

Remove automatic recovery!?

Since the error handling should be aligned more closely to the official API (see #26), some automatic recovery features should either be removed or be hidden behind a lax flag.

The following code snippet is one of the examples that should be revisited:

if (('@value' === $keyword) || ('@language' === $keyword) || ('@annotation' === $keyword)) {
    if (false === $frame) {
        if (is_array($value) && (1 === count($value))) {
            $value = $value[0];
        }

Allow "@id": {} in frames

Currently this triggers a SyntaxException:

Invalid value for @id detected (must be a string) (near {}).

Keyword aliasing doesn't work with @vocab

Handle relative IRIs properly

See RFC3986

Graph::createNode() should allow reusage of blank-nodes

Currently, createNode() creates new blank node each time it gets _:something. The problem is, that, sometimes, it is desirable to reference the same blank node several times (node itself, then some other nodes, which point to it)

The solution is, to keep some kind of cache for blank-nodes, just as there is a cache for "regular" nodes

Implement language maps

{
  "@context": {
    "label": {
      "@id": "http://example.com/label",
      "@container": "@language"
    }
  },
  "@id": "http://buckingham.uk/queenie",
  "label": {
    "en": "The Queen",
    "de": "Die Koenigin"
  }
}

Should expanded to:

[
  {
    "@id": "http://buckingham.uk/queenie",
    "http://example.com/label": [
      { "@value": "The Queen", "@language": "en" },
      { "@value": "Die Königin", "@language": "de" }
    ]
  }
]

It is still being discussed if non-literal values have to be round-tripable and how: json-ld/json-ld.org#159

Add helper method to convert literals to native types

This feature should also be accessible from a JSON-LD frame and not just via a helper method or flag. See the referenced PR request below for such a use case.

Implement annotations

There's a bug when flattening this document

{
  "@context": { "@vocab": "hydra:", "targetUrl": { "@reverse": "operations", "@type": "@id" } },
  "@type": "Event",
  "action": { 
    "@type": "RsvpAction",
    "targetUrl": "https://events-organizer.com/rsvp?eventId=123",
    "method": "POST",
    "expects": {
      "supportedProperties": {
        "property": "rsvpStatus",
        "required": true
      }
    }
  }
}

The blank nodes are not labeled properly.

Fix PSR links (and check other links)

The PSR links in the README are broken since the document names have been changed.

Implement property generators

For example the following

{
  "@context": {
    "title": { "@id": [
         "http://purl.org/dc/terms/title",
         "http://schema.org/name",
         "http://www.w3.org/2000/01/rdf-schema#label"
    ] }
  },
  "@id": "http://example.com/book",
  "title": "The Count of Monte Cristo"
}

should be expanded to

[ {
  "@id": "http://example.com/book",
  "http://purl.org/dc/terms/title": [ 
     { "@value": "The Count of Monte Cristo" } ],
  "http://schema.org/name": [
    { "@value": "The Count of Monte Cristo" } ],
  "http://www.w3.org/2000/01/rdf-schema#label": [
    { "@value": "The Count of Monte Cristo" } ]
} ]

Add support for keyword aliasing in compaction

Keyword aliases are currently just supported in expansion

Handle UTF8 characters correctly

UTF8 characters are escaped at the moment. They should be represented as UTF8 chars in the result instead

Ensure null values in @type are removed

Since terms can now be explicitly mapped to null, it is possible that values in @type expand to null. These should be removed in expansion:

{
  "@context": {
    "@vocab": "http://xmlns.com/foaf/0.1/",
    "Person": { "@id": null }
  },
  "@id": "http://me.markus-lanthaler.com/",
  "name": "Markus Lanthaler",
  "@type": "Person",
  "Person": "should be removed as well"
}

toQuads missing

The README gives the example

$quads = JsonLD::toQuads('document.jsonld');

but toQuads is not implemented.

Support HHVM

Currently, a lot of tests fail. Investigate the reason and fix it or file a bug for HHVM.

Boolean type is returned as string

I noticed that when you send a boolen it will be returned as a string. For example true ends up as "true".

{
"@context":{
"active":"http://localhost/app_dev.php/hydra/vocab#SomeDTO/active"
},

"@type":"http://localhost/app_dev.php/hydra/vocab#SomeDTO",
"active":true
}

I tried to add a unit test for it but the unit testing failed. With

PHP Warning:  file_get_contents(/../vendor/ml/json-ld/ML/JsonLD/Test/tests/expand-manifest.jsonld): failed to open stream: No such file or directory in /../vendor/ml/json-ld/ML/JsonLD/Test/TestManifestIterator.php on line 44

Which is correct because there is no test directory??

How should the unit test be started so that I can add a unit test and try to fix this for boolean type?

Add flag to ignore property generators

GraphInterface::getNodes() missing value and type nodes

Using this example document

{
    "@id": "http://example.info/node1",
    "http://example.info/testproperty1":
    [ 
        {"@value": "value1", "@type": "http://www.w3.org/2001/XMLSchema#string"},
        {"@value": "value3"}
    ],
    "http://example.info/testproperty2": {"@value": "value2", "@type": "http://www.w3.org/2001/XMLSchema#string"},
    "http://example.info/testproperty3": {"@id": "http://example.info/node2"}
}

when calling GraphInterface::getNodes(), I would expect 6 nodes (3 named nodes, 2 typed value nodes, 1 value node). But I only get 2 nodes (http://example.info/node1 and http://example.info/node2) .

NodeInterface::getProperties() - Only the last TypedValue in a set is returned

Working with this example jsonld doc

{
    "@id": "http://example.info/node1",
    "http://example.info/testproperty1":
    [ 
        {"@value": "value1", "@type": "http://www.w3.org/2001/XMLSchema#string"}, 
        {"@value": "value2", "@type": "http://www.w3.org/2001/XMLSchema#string"}, 
        {"@value": "value3"}
    ]
}

when using NodeInterface::getProperties() only the last TypedValue node will be returned.

In the case of the upper document I get the nodes with value2 and value3. When I give the value3 node a type, only this node will be returned.

LanguageTagged nodes are fine.

Implement conversion to RDF

Example of parsing an N-Quad's document?

The playground is able to parse my sample N-Quad RDF data - but I can't figure out how I'm supposed to load and parse the file using JsonLD.

$file = trim(file_get_contents($file));
$result = ML\JsonLD\NQuads::parse($file);
print_r($result);

$nquads = new ML\JsonLD\NQuads();
$quads = $nquads->parse($file);
$document = JsonLD::fromRdf($quads);

Add support for HTTP libraries (support PSR-7)

Currently file_get_contents is used to retrieve remote contexts and documents. This isn't really flexible and should sooner or later be replaced with a more sophisticated library.

Keep an eye on the PHP FIG Proposal for a HTTP Client interface.

Use the context's IRI as base IRI when processing remote contexts

Throw error if alias for @context is found

@context can't be aliased.

Allow @id: null to decouple a term from @vocab

{
  "@context": {
    "@vocab": "http://example.org/vocab#",
    "date": { "@id": null }
  },
  "@id": "example1",
  "date": "test"
}

date should not expand to http://example.org/vocab#date in this case

Drop free-floating nodes when serializing a Document

So, e.g. in sample-serialized-document.jsonld the following node shouldn't be there:

{
  "@id": "http://example.com/t1"
}

Undocumented dependency for regex parsing in IRI.php?

The parse() function of IRI.php works fine for me on a Centos 6/PHP 5.3.3 installation. It fails however on Centos 5 (with rpm package php53/PHP 5.3.3 installed).

I could track it down to to following lines of code (first and last line added for demonstration):

    $iri = 'http://www.w3.org/2004/02/skos/core#hiddenLabel';

    // Parse IRI by using the regular expression as specified by
    // http://tools.ietf.org/html/rfc3986#appendix-B
    $regex = '|^((?P<scheme>[^:/?#]+):)?' .
                '((?P<doubleslash>//)(?P<authority>[^/?#]*))?(?P<path>[^?#]*)' .
                '((?<querydef>\?)(?P<query>[^#]*))?(#(?P<fragment>.*))?|';
    preg_match($regex, $iri, $match);

    print $match['scheme'] . "\n";

On Centos 6, "http" is printed.

On Centos 5, I get the message:

PHP Warning: preg_match(): Compilation failed: unrecognized character after (?< at offset 89 in [...]temp.php on line 9

without any other output.

Perhaps I'm missing some unknown dependency - help much appreciated.

Cheers, Joachim