Skip to content

Clarify JSON-LD extension vocabulary composition #927

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jviotti wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Clarify JSON-LD extension vocabulary composition #927

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 14 additions & 10 deletions schemas/sourcemeta-extension/v1/README.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,10 +50,12 @@ This keyword has no effect on any other keyword.

The keywords in this section map the instance locations that their subschemas
successfully evaluate to nodes, literals, and edges of a JSON-LD document. A
keyword takes effect at every instance location its subschema evaluates. When
several subschemas annotate the same instance location, their annotations are
merged, and a keyword that takes a single value MUST NOT be assigned two
different values for the same location.
keyword takes effect at every instance location its subschema evaluates,
including across references, so annotations declared in different schemas may
meet at the same instance location. When they do, their values are merged, and
identical values always collapse into one, so a schema and the schemas it
references may safely declare the same annotation. A keyword that takes a
single value MUST NOT be assigned two different values for the same location.

@cubic-dev-ai cubic-dev-ai Bot Jul 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Spec contradiction: the general merging rule forbids assigning two different values to a single-value keyword at the same location, but x-jsonld-id immediately describes merging distinct values at the same location. Since x-jsonld-id takes a single absolute IRI, the general rule and the keyword-specific rule cannot both be correct. This will confuse implementers trying to decide whether multiple x-jsonld-id annotations at the same location are valid. Recommend clarifying in the general section that keywords with custom merging semantics in their own section are exempt, or constraining the x-jsonld-id text to avoid contradicting the general rule.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At schemas/sourcemeta-extension/v1/README.markdown, line 58:

<comment>Spec contradiction: the general merging rule forbids assigning two different values to a single-value keyword at the same location, but x-jsonld-id immediately describes merging distinct values at the same location. Since x-jsonld-id takes a single absolute IRI, the general rule and the keyword-specific rule cannot both be correct. This will confuse implementers trying to decide whether multiple x-jsonld-id annotations at the same location are valid. Recommend clarifying in the general section that keywords with custom merging semantics in their own section are exempt, or constraining the x-jsonld-id text to avoid contradicting the general rule.</comment>

<file context>
@@ -50,10 +50,12 @@ This keyword has no effect on any other keyword.
+meet at the same instance location. When they do, their values are merged, and
+identical values always collapse into one, so a schema and the schemas it
+references may safely declare the same annotation. A keyword that takes a
+single value MUST NOT be assigned two different values for the same location.
 
 #### 3.2.1. `x-jsonld-id`
</file context>
Suggested change
single value MUST NOT be assigned two different values for the same location.
single value MUST NOT be assigned two different values for the same location, unless this vocabulary defines specific merging behavior for that keyword in its own section.


#### 3.2.1. `x-jsonld-id`

Expand All @@ -64,16 +66,17 @@ This keyword declares the predicate IRI that connects the annotated instance
location, as the object, to its enclosing node. It MUST NOT be applied to the
document root, to an array element, or to a member of a location annotated
with `x-jsonld-container`, as such locations have no enclosing node to attach
a predicate to.
a predicate to. Distinct values that meet at the same location merge,

@augmentcode augmentcode Bot Jul 16, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In schemas/sourcemeta-extension/v1/README.markdown (line 69), the text says distinct x-jsonld-id values that meet at the same location “merge”, but earlier this section states single-value keywords MUST NOT be assigned two different values for the same location and x-jsonld-id is defined as a single string. Could you clarify whether x-jsonld-id is intended to be multi-valued across schema composition, or whether distinct values should be treated as invalid?

Severity: medium

Other Locations
  • schemas/sourcemeta-extension/v1/README.markdown:57
  • schemas/sourcemeta-extension/v1/README.markdown:58
  • schemas/sourcemeta-extension/v1/README.markdown:91

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.

asserting the location under each declared predicate.

#### 3.2.2. `x-jsonld-type`

The value of this keyword MUST be a string representing an absolute IRI
[RFC3987], or an array of such strings.

This keyword declares the `@type` of the node that the annotated instance
location materializes as. Duplicate entries are collapsed, and an empty array
declares no types. It MUST be applied to a location whose value is an object,
location materializes as. Values that meet at the same location merge into the

@augmentcode augmentcode Bot Jul 16, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In schemas/sourcemeta-extension/v1/README.markdown (line 78), x-jsonld-type allows either a string or an array, but the new “merge into the union” wording doesn’t state how mixed shapes (string vs array) are normalized when they meet at the same location. This ambiguity could lead to inconsistent implementations of the merge rule.

Severity: low

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.

@cubic-dev-ai cubic-dev-ai Bot Jul 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: The merge semantics here ('Values that meet at the same location merge into the union of the declared types') don't specify how a bare string value and an array value are reconciled when they meet at the same location. Since the keyword accepts either a string or an array, implementers may handle the mixed-shape case differently. Consider adding a note that a lone string is treated as a single-element array for the purposes of union merging.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At schemas/sourcemeta-extension/v1/README.markdown, line 78:

<comment>The merge semantics here ('Values that meet at the same location merge into the union of the declared types') don't specify how a bare string value and an array value are reconciled when they meet at the same location. Since the keyword accepts either a string or an array, implementers may handle the mixed-shape case differently. Consider adding a note that a lone string is treated as a single-element array for the purposes of union merging.</comment>

<file context>
@@ -64,16 +66,17 @@ This keyword declares the predicate IRI that connects the annotated instance
 This keyword declares the `@type` of the node that the annotated instance
-location materializes as. Duplicate entries are collapsed, and an empty array
-declares no types. It MUST be applied to a location whose value is an object,
+location materializes as. Values that meet at the same location merge into the
+union of the declared types, and an empty array declares no types. It MUST be applied to a location whose value is an object,
 unless the location is promoted to an identified node with `x-jsonld-self`.
</file context>

union of the declared types, and an empty array declares no types. It MUST be applied to a location whose value is an object,
unless the location is promoted to an identified node with `x-jsonld-self`.

#### 3.2.3. `x-jsonld-reverse`
Expand All @@ -85,8 +88,8 @@ This keyword declares a reverse predicate IRI, asserting the edge with the
annotated instance location as the subject and the enclosing node as the
object, emitted through the JSON-LD `@reverse` keyword. The annotated location
MUST materialize as a node or as an array of nodes, as a literal cannot be the
subject of an edge. The placement requirements of `x-jsonld-id` also apply to
this keyword.
subject of an edge. The placement and merging behavior of `x-jsonld-id` also
apply to this keyword.

#### 3.2.4. `x-jsonld-datatype`

Expand All @@ -106,7 +109,8 @@ tag [RFC5646].

This keyword declares the language of the language-tagged literal that the
annotated instance location materializes as. It MUST be applied to a location
whose value is a string.
whose value is a string. Tags compare case-insensitively, and the first

@augmentcode augmentcode Bot Jul 16, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In schemas/sourcemeta-extension/v1/README.markdown (line 112), “the first declared spelling is kept” is unclear when annotations can meet across references, since “first” may depend on evaluation/ref resolution order. If output casing is intended to be deterministic, this may need a more precisely defined rule.

Severity: low

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.

@cubic-dev-ai cubic-dev-ai Bot Jul 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The phrase 'the first declared spelling is kept' is ambiguous when tags can arrive from different schemas via references. 'First' could mean lexical document order, evaluation order, or ref-resolution order—each of which may differ across implementations. If deterministic output casing is intended, consider defining 'first' more precisely (e.g., 'the spelling in the outermost schema' or 'the spelling encountered earliest in evaluation order').

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At schemas/sourcemeta-extension/v1/README.markdown, line 112:

<comment>The phrase 'the first declared spelling is kept' is ambiguous when tags can arrive from different schemas via references. 'First' could mean lexical document order, evaluation order, or ref-resolution order—each of which may differ across implementations. If deterministic output casing is intended, consider defining 'first' more precisely (e.g., 'the spelling in the outermost schema' or 'the spelling encountered earliest in evaluation order').</comment>

<file context>
@@ -106,7 +109,8 @@ tag [RFC5646].
 This keyword declares the language of the language-tagged literal that the
 annotated instance location materializes as. It MUST be applied to a location
-whose value is a string.
+whose value is a string. Tags compare case-insensitively, and the first
+declared spelling is kept.
 
</file context>

declared spelling is kept.

#### 3.2.6. `x-jsonld-direction`

Expand Down
Loading