[jdsika]

Mirror of linkml#4144, same head. Review there; this PR tracks the fork stack.

2026-10-23, second push: @version is now emitted only when the context uses a JSON-LD 1.1 construct, the conditional form offered under "Areas of uncertainty" before. A context without one stays loadable by a JSON-LD 1.0 processor, so 20 files the first version changed are back to main.

Summary

A generated JSON-LD context that uses a JSON-LD 1.1 construct now starts with "@version": 1.1.

{"@context": {"@version": 1.1, "xsd": "http://www.w3.org/2001/XMLSchema#", ...}}

gen-jsonld-context emits JSON-LD 1.1 constructs at three points: a scoped @context on enum slots (ENUM_CONTEXT, the @vocab coercion of linkml#3447), type-scoped contexts for class-level range overrides (linkml#3336), and @prefix: true for a namespace that ends in neither / nor #.

• A JSON-LD 1.0 processor ignores term-definition entries it doesn't know (1.0 API §6.2), so it drops these coercions without an error. For example, rdflib in 1.0 mode reads a float override as "1.5"^^xsd:double.
• @version is the declaration for this: "The use of 1.1 for the value of @version is intended to cause a JSON-LD 1.0 processor to stop processing" (JSON-LD 1.1 §1.7). A 1.1 processor set to json-ld-1.0 reports a processing mode conflict (1.1 API §4.1.2, step 5.5.2).

The generator marks those three points, so there is no keyword table, and the declaration follows what the output contains. --no-model leaves out the scoped contexts and --no-prefixes the @prefix entries; without them the context is plain JSON-LD 1.0 and has no version line. gen-jsonld embeds the generated context under the same rule. gen-prefix-map emits a plain prefix map, not a JSON-LD context.

linkml#1995 (for linkml#1993) sets version="1.1" where LinkML itself parses JSON-LD, and linkml#25 proposed @version but was closed without it. The declaration covers every other consumer of a published context.

Closes #55

How was this tested?

• test_version_is_declared_exactly_when_a_json_ld_1_1_construct_is_used: a scoped context, an enum and @prefix each declare the version; a plain schema, --no-model and --no-prefixes don't.
• test_context_with_a_json_ld_1_1_construct_declares_it: the value is the number 1.1, first in the context.
• test_embedded_context_follows_the_same_rule: gen-jsonld's embedded context.
• test_type_scoped_coercion_survives_json_ld_1_0_processing: data parsed by rdflib with version=1.0 keeps the xsd:float of a class-level override. It fails without this change (xsd:double).
• Snapshots, including the slow metamodel and Biolink ones: each diff is the added line. Across the 35 contexts in the test snapshots and docs, the line appears exactly where @prefix or a scoped context does; tutorial 4's context uses neither and is unchanged.
• Local, on this head: default suite 14,299 passed, 1 failed (test_datadict_personinfo, which fails on main too in this environment); slow suite (--with-slow --with-biolink -m "slow and not kroki") 67 passed.

Areas of uncertainty

• A JSON-LD 1.1 construct added to the generator later needs the same mark; the parametrized test names the three that exist.
• The metamodel contexts published by linkml-model use @prefix, so they gain the line when they are next generated.

Checklist

• My code follows the contributor guidelines
• I have added tests that prove my fix/feature works
• Existing tests pass locally with my changes

AI Assistance

If you used AI tools while preparing this PR, you are still the author and responsible for understanding, verifying, and defending your submission. Please engage with reviewers personally rather than through your agent during feedback and revisions. See our AI Covenant for details.