README

A PHP implementation of the JSON-LD 1.1 specification.

Status: Pre-1.0. v0.1.0 ships the JSON-LD code extracted from accredifysg/verifiable-credentials-php. It is functionally complete for VCv2 / Open Badges v3 expansion but is not yet spec-compliant with JSON-LD 1.1 — see CHANGELOG for known limitations. The public API may change before v1.0.

Goals

• Faithful implementation of the JSON-LD 1.1 algorithms defined in the JSON-LD 1.1 Processing Algorithms and API.
• Pluggable document loader so consumers (e.g. verifiable-credential libraries) can serve known @context URLs from local resources.
• No mandatory HTTP client dependency — bring your own (Guzzle is suggested, not required).
• Tested against the official W3C JSON-LD test suite.

Planned scope (v1.0)

• Custom DocumentLoader interface
• [~] Expansion (§5.5) — implemented; ~352/385 of the W3C expand suite
• [~] Compaction (§5.6) — implemented incl. container-maps (incl. property-valued @index, @type-map node refs), keyword recursion, @nest, nested @list, @graph maps, @reverse, value-aware term selection, property-/type-scoped contexts with scoped @base, IRI relativisation, expand-first normalisation, @type-set arrays; ~210/246 of the W3C compact suite
• [~] Serialize JSON-LD to RDF (§7 / toRdf) — implemented; ~423/467 of the W3C toRdf suite (N-Quads output incl. rdfDirection; generalized RDF pending)

Suite numbers from v0.42.0 use the spec-accurate toEqual comparison (object-key order insignificant, array order significant); earlier numbers used a looser comparison and are not directly comparable — see the CHANGELOG.

Out of scope for v1.0: Flattening, Framing, RDF-to-JSON-LD (fromRdf).

Installation

composer require accredifysg/php-json-ld:^0.1

Requires PHP 8.1+. You also need a PSR-18 HTTP client + PSR-17 request factory if you use the bundled HttpDocumentLoader (e.g. guzzlehttp/guzzle and guzzlehttp/psr7), or you can implement DocumentLoader yourself to serve @context URLs from wherever you like.

Usage

use Accredify\JsonLd\JsonLdProcessor;
use Accredify\JsonLd\Loaders\CachingDocumentLoader;
use Accredify\JsonLd\Loaders\HttpDocumentLoader;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;

$loader = new CachingDocumentLoader(
    new HttpDocumentLoader(new Client, new HttpFactory),
);

$processor = new JsonLdProcessor($loader);
$expanded = $processor->expand($yourDocument)->toArray();

If you want to serve known contexts from local files (recommended for verifiable credentials), implement Accredify\JsonLd\Contracts\DocumentLoader yourself. See tests/Algorithms/Characterization/Support/BundledContextLoader.php for an example.

Compliance

The package is tested against the official W3C JSON-LD 1.1 test suite, pulled in as a git submodule at tests/w3c/. See tests/W3c/README.md for harness layout and how to run it.

# Run only the project's unit tests (the default)
composer test

# Run the W3C conformance suite
composer test:w3c

A per-algorithm PASS/FAIL matrix will appear in this section once Phase 4 is in progress (see the plan).

Characterization fixtures

tests/Algorithms/Characterization/ holds JSON snapshots of the expander's output, generated from running the original accredifysg/verifiable-credentials-php JsonLdProcessor over a set of sample documents. They are NOT a spec-conformance reference — they pin the package's current quirky behaviour so that spec-correctness work in later phases can land each behaviour change in a reviewable diff.

When a Phase 4 PR changes expansion in a way that updates these fixtures, the update should be reviewed for correctness and paired with any matching change in downstream consumers (e.g. VC's signed-credential test fixtures).

License

MIT © Accredify