JSON-LD Contexts

Note

When run with --emit-frame, the generator writes a .frame.jsonld with @embed directives derived from slot inlined settings (@always / @never).

Example:

gen-jsonld-context schema.yaml --output schema.context.jsonld --emit-frame

This produces two files:

  • schema.context.jsonld – the JSON-LD context

  • schema.frame.jsonld – the JSON-LD frame (only if @embed rules are present)

Alternatively, you can embed the context directly into the frame and produce a single file:

gen-jsonld-context schema.yaml --output schema.jsonld --embed-context-in-frame

This produces one file:

  • schema.frame.jsonld – the JSON-LD frame with the full @context embedded

--emit-frame and --embed-context-in-frame require --output.

Warning

The JSON-LD context generator does not yet include @type directives except at the top level.

Overview

JSON-LD context provides mapping from JSON to RDF.

gen-jsonld-context personinfo.yaml > personinfo.context.jsonld

You can control the output via prefixes declarations and default_curi_maps.

Any JSON that conforms to the derived JSON Schema (see above) can be converted to RDF using this context.

CURIE usage

By default, JSON-LD context keys use the generator’s normal slot-name alias. With --use-curies, non-identifier slots use their CURIEs (for example, demo_id with slot_uri: demo:id becomes demo:id). Identifier slots marked identifier: true are an exception: their slot-name key (id in the example) maps to @id and is never replaced by a CURIE, even if the slot declares a slot_uri. Class context keys are CURIE-keyed as well.

The CURIE mode is opt-in. CURIEs are resolved with SchemaView.get_curie using the schema’s prefixes and default prefix.

Example (ex is the schema’s default_prefix):

prefixes:
  ex: https://example.org/
  demo: https://example.org/demo/
default_prefix: ex

classes:
  Entity:
    slots:
      - id
      - demo_id

slots:
  id:
    range: string
    required: true
    identifier: true
  demo_id:
    range: string
    slot_uri: demo:id

With gen-jsonld-context --use-curies, id remains the context key and maps to @id; demo_id is keyed as demo:id.

Treatment of OBO prefixes

All OBO ontologies use prefixes that end in underscores (for example http://purl.obolibrary.org/obo/PATO_). Note that the JSON-LD 1.1 spec doesn’t allow trailing underscores on simple “flat” prefix maps, i.e this is not correct:

"@context": {
    "PATO": "http://purl.obolibrary.org/obo/PATO_",
     }

It must be represented as:

"@context": {
    "PATO": {
         "@id": "http://purl.obolibrary.org/obo/PATO_",
          "@prefix": true
     }

However, the former can still be convenient, so this can be done with a flag:

gen-jsonld-context --flatprefixes personinfo.yaml > personinfo.context.jsonld

However, this is not recommended and newer applications should switch to gen-prefix-map:

gen-prefix-map --flatprefixes personinfo.yaml > personinfo.prefixmap.json

Docs

Command Line

gen-jsonld-context

Generate jsonld @context definition from LinkML model

gen-jsonld-context [OPTIONS] YAMLFILE

Options

--base <base>

Base URI for model

--prefixes, --no-prefixes

Emit context for prefixes (default=–prefixes)

Default:

True

--model, --no-model

Emit context for model elements (default=–model)

Default:

True

--flatprefixes, --no-flatprefixes

Emit non-JSON-LD compliant prefixes as an object (deprecated: use gen-prefix-map instead).

Default:

False

--emit-frame, --no-emit-frame

Also emit a <schema>.frame.jsonld file with @embed rules for framing

Default:

False

--embed-context-in-frame, --no-embed-context-in-frame

Emit a <schema>.frame.jsonld file with @context embedded directly (single file)

Default:

False

-o, --output <output>

Output file name

--fix-multivalue-containers, --no-fix-multivalue-containers

For multivalued attributes declare a fix container type (‘@set’ for lists, ‘@index’ for dictionaries).

Default:

False

--exclude-imports, --include-imports

Use –exclude-imports to exclude imported elements from the generated JSON-LD context. This is useful when extending an ontology whose terms already have context definitions in their own JSON-LD context file.

Default:

False

--exclude-external-imports, --no-exclude-external-imports

Exclude elements from URL-based external vocabulary imports while keeping local file imports. Useful when extending ontologies (e.g. W3C VC v2) whose terms are @protected in their own JSON-LD context.

Default:

False

--xsd-anyuri-as-iri, --no-xsd-anyuri-as-iri

Map xsd:anyURI-typed ranges (uri, uriorcurie) to @type: @id instead of @type: xsd:anyURI.

Default:

False

--use-curies, --not-use-curies

Use class_uri/slot_uri CURIEs as class and non-identifier slot context keys; identifier slots retain their slot-name key and map to @id.

Default:

False

-V, --version

Show the version and exit.

-f, --format <format>

Output format

Default:

'context'

Options:

context | json

--metadata, --no-metadata

Include metadata in output

Default:

True

--generation-date, --no-generation-date

Stamp output with the generation_date timestamp. Off by default so output is reproducible across runs.

Default:

False

--useuris, --metauris

Use class and slot URIs over model uris

Default:

True

-im, --importmap <importmap>

Import mapping file

--log_level <log_level>

Logging level

Default:

'WARNING'

Options:

CRITICAL | ERROR | WARNING | INFO | DEBUG

-v, --verbose

Verbosity. Takes precedence over –log_level.

--mergeimports, --no-mergeimports

Merge imports into source file (default=mergeimports)

--stacktrace, --no-stacktrace

Print a stack trace when an error occurs

Default:

False

Arguments

YAMLFILE

Required argument

Code

class linkml.generators.jsonldcontextgen.ContextGenerator(schema: Union[str, TextIO, linkml_runtime.linkml_model.meta.SchemaDefinition, ForwardRef('Generator'), pathlib.Path], schemaview: linkml_runtime.utils.schemaview.SchemaView | None = None, format: str | None = None, metadata: bool = False, include_generation_date: bool = False, useuris: bool | None = None, log_level: int | None = 30, mergeimports: bool | None = True, source_file_date: str | None = None, source_file_size: int | None = None, logger: logging.Logger | None = None, verbose: bool | None = None, output: str | None = None, namespaces: linkml_runtime.utils.namespaces.Namespaces | None = <property object at 0x7f190c7660c0>, directory_output: bool = False, base_dir: str = None, metamodel_name_map: dict[str, str] = None, importmap: str | collections.abc.Mapping[str, str] | None = None, emit_prefixes: set[str] = <factory>, metamodel: linkml.utils.schemaloader.SchemaLoader = None, stacktrace: bool = False, include: str | pathlib.Path | linkml_runtime.linkml_model.meta.SchemaDefinition | None = None, default_ns: str = None, context_body: dict = <factory>, slot_class_maps: dict = <factory>, model: bool | None = True, base: str | rdflib.namespace.Namespace | None = None, prefixes: bool | None = True, flatprefixes: bool | None = False, fix_multivalue_containers: bool | None = False, exclude_imports: bool = False, exclude_external_imports: bool = False, _local_classes: set | None = None, _local_slots: set | None = None, _external_classes: set | None = None, _external_slots: set | None = None, use_curies: bool = False, xsd_anyuri_as_iri: bool = False, emit_frame: bool = False, embed_context_in_frame: bool = False, frame_body: dict = <factory>, frame_root: str | None = None)[source]
serialize(base: str | Namespace | None = None, output: str | None = None, prefixes: bool | None = None, flatprefixes: bool | None = None, model: bool | None = None, **kwargs) → str[source]

Generate output in the required format

Parameters:

kwargs – Generator specific parameters

Returns:

Generated output, or None if the generator writes its output directly to disk instead of returning it (e.g. ExcelGenerator, JavaGenerator)