README

A PHP implementation of the JSON-LD 1.1 specification.

Status: stable (1.0). The public API is stable and the project follows Semantic Versioning — breaking changes bump the major version. v1.0.0 delivers spec-compliant JSON-LD 1.1 Expansion, Compaction, and Serialize to RDF (toRdf), validated against the official W3C JSON-LD 1.1 test suite — see the compliance matrix for per-algorithm conformance and the CHANGELOG for the enumerated residual blockers. Flattening, Framing, and RDF-to-JSON-LD (fromRdf) remain out of scope for the 1.x line.

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.

Scope (delivered in v1.0)

• Custom DocumentLoader interface
• Expansion (§5.5) — 378/385 of the W3C expand suite (the remaining 7 are environment/spec-accommodation blockers)
• Compaction (§5.6) — 246/246 of the W3C compact suite (100%): container-maps (incl. property-valued @index, @type-map node refs), keyword recursion, @nest, nested @list, @graph maps, @reverse (incl. per-value term selection and containers), full inverse-context term scoring (list/direction-aware, @json literals), property-/type-scoped contexts with scoped @base/@vocab, IRI relativisation, expand-first normalisation, the compactArrays option, §5.7 prefix rules and error conditions
• Serialize JSON-LD to RDF (§7 / toRdf) — 460/467 of the W3C toRdf suite (the remaining 7 are environment/spec-accommodation blockers); N-Quads output incl. rdfDirection, produceGeneralizedRdf, and JCS @json canonicalization

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:^1.0

Requires PHP 8.2+. 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

Conformance matrix (v1.0.0)

Totals: 1084 / 1098 passing across the three in-scope manifests; Compaction is fully conformant. The 14 residual non-conformances (7 in the expand manifest, 7 in toRdf) are 9 distinct test IDs — five shared by both manifests plus a couple unique to each — and are mostly environment / spec-accommodation limits, with a few minor validation gaps:

• #tc031 — context uses a relative URL resolving outside the offline fixture base
• #tc032 / #tc033 — unused embedded contexts aren't validated (negative tests)
• #ter56 — redefining the @context keyword isn't rejected (negative test)
• #t0128 (expand) / #te128 (toRdf) — two scoped contexts sharing a context trip the offline circular-reference guard
• #tin06 — the json.api @included-blocks example produces a different shape
• #t0122 (expand only) — keyword-shaped (@) IRIs are kept rather than ignored
• #tjs10 (toRdf only) — JSON-literal structural canonicalization differs

These are carried as an explicit expected-failure allowlist (tests/W3c/KnownBlockers.php) so the conformance suite stays green and gates CI — any new regression, or a listed blocker that starts passing, fails the build. See the CHANGELOG and tests/W3c/README.md for the full release-over-release history.

Counts use the spec-accurate toEqual comparison (object-key order insignificant, array order significant) introduced in v0.42.0; earlier figures used a looser comparison and are not directly comparable.

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 behaviour so that any change to expansion output lands as a reviewable diff.

When a 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