`FrozenDocumentLoader`¶

Document loader that serves only a sealed allowlist of URLs.

documents maps each allowed URL to either a parsed JSON-LD dict or a pathlib.Path pointing to a JSON file on disk. Path entries are read and parsed lazily on first request, then cached in place so subsequent calls skip the file read. Any URL not present in the mapping raises JsonLdError with code 'loading document failed'.

With no arguments, a FrozenDocumentLoader serves the curated BUNDLED_CONTEXTS set. To extend rather than replace the bundle::

FrozenDocumentLoader(documents=dict(BUNDLED_CONTEXTS, **extras))

Parameters:

Name	Type	Description	Default
`documents`	`Mapping[str, dict \| Path] \| None`	allowlist mapping each URL to a parsed JSON-LD `dict` or a `pathlib.Path` to a JSON file; defaults to `BUNDLED_CONTEXTS`.	`None`

FrozenDocumentLoader serves only URLs in an allowlist and refuses all other document loads. It is intended for air-gapped runs, reproducible builds, and deployments that must avoid remote context fetching.

With no arguments, the loader serves the curated BUNDLED_CONTEXTS mapping:

Example frozen_default.py

import json

from pyld import FrozenDocumentLoader, jsonld

doc = {
    "@context": {"name": "http://schema.org/name"},
    "name": "Earth",
}

loader = FrozenDocumentLoader()
result = jsonld.expand(doc, options={"documentLoader": loader})
print(json.dumps(result, indent=2))

Output

[
  {
    "http://schema.org/name": [
      {
        "@value": "Earth"
      }
    ]
  }
]

Bundled Contexts¶

Context URL	Bundled file
`https://w3id.org/security/suites/ed25519-2020/v1`	`security-ed25519-2020-v1.jsonld`
`https://w3id.org/security/suites/jws-2020/v1`	`security-jws-2020-v1.jsonld`
`https://w3id.org/security/v1`	`security-v1.jsonld`
`https://w3id.org/security/v2`	`security-v2.jsonld`
`https://www.w3.org/2018/credentials/v1`	`credentials-v1.jsonld`
`https://www.w3.org/ns/activitystreams`	`activitystreams.jsonld`
`https://www.w3.org/ns/credentials/v2`	`credentials-v2.jsonld`
`https://www.w3.org/ns/did/v1`	`did-v1.jsonld`

Extend the bundled mapping with additional vetted contexts:

Example frozen_extend.py

import json

from pyld import BUNDLED_CONTEXTS, FrozenDocumentLoader, jsonld

loader = FrozenDocumentLoader(
    documents=dict(
        BUNDLED_CONTEXTS,
        **{
            "https://example.com/context": {
                "@context": {"name": "https://schema.org/name"}
            }
        },
    )
)

doc = {
    "@context": "https://example.com/context",
    "name": "Earth",
}

result = jsonld.expand(doc, options={"documentLoader": loader})
print(json.dumps(result, indent=2))

Output

[
  {
    "https://schema.org/name": [
      {
        "@value": "Earth"
      }
    ]
  }
]

The documents mapping may contain parsed JSON-LD dictionaries or pathlib.Path instances pointing to JSON files. Path entries are read lazily and cached after the first request.

Any URL outside the allowlist raises JsonLdError with code loading document failed.

FrozenDocumentLoader¶

Bundled Contexts¶

`FrozenDocumentLoader`¶