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.

Values of uri, uriorcurie, the types derived from them, and the node types objectidentifier and nodeidentifier are coerced to @id; a type derived from string with uri: xsd:anyURI keeps URI references as xsd:anyURI literals (see Links and URI references).

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

Deprecated and without effect: values of uri, uriorcurie and the types derived from them are always IRIs.

--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 0x7f8044f54ef0>, 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 | None = None, emit_frame: bool = False, embed_context_in_frame: bool = False, frame_body: dict = <factory>, frame_root: str | None = None)

serialize(base: str | Namespace | None = None, output: str | None = None, prefixes: bool | None = None, flatprefixes: bool | None = None, model: bool | None = None, **kwargs) → str

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)