improve 'term definition' definition

[pchampin]

I'm not entirely satisfied with the addition in common/terms.html, as it seems too detailed for the terminology section. But...

...as pointed out in the comment of #630,
the API spec references to this definition in multiple places, and many of those links are actually for instances of the internal representation, not for instances of the strings or maps that represent term definition in JSON.

So the alternative would be to introduce a new name for those "internal term definition" and patch all the algorithms... which seems laborious and error-prone.

@gkellogg I don't remember what's the process for synchronizing the files in common with other specs.

---

Preview | Diff

[gkellogg]

@gkellogg I don't remember what's the process for synchronizing the files in common with other specs

Just needs to be copied. The GH Action checks out common and compares the results.

[pchampin]

This one probably also needs to be formatted as a candidate amendment...
And a corresponding one will be needed in json-ld-syntax.

[gkellogg]

The problem with this is that that will show up in syntax and framing, as well.

[pchampin]

yes, that's why I named it change_api_638 insteal of change_8. That way, we can add a change marker in the other specs without an ID clash.

[gkellogg]

We'll need issues for those other specs to have their own version of this update.

[pchampin]

good point. This is now done:

• reflect change in common from w3c/json-ld-api#638 once merged json-ld-syntax#454
• reflect change in common from w3c/json-ld-api#638 once merged json-ld-framing#171

[gkellogg]

I created w3c/json-ld-syntax#461 to track this in Syntax, so I think we can probably merge this now.

[w3cbot]

This was discussed during the #json-ld meeting on 04 June 2025.

View the transcript

w3c/json-ld-api#638

<gb> Pull Request 638 address #630 (by pchampin) [needs discussion] [class-2]

pchampin: This is about inverse context creation.
… I thought it was ambiguous in the definition of the active context.
… I tried to improve it without restructuring the document, which meant changing something in the terminology section.
… The end result is not 100% satisfying, as change to terminology is big.
… It's also inherited in other documents, so we need to mark changes in other documents, even though it's only in JSON-LD API.

bigbluehat: thoughts? especially on the size of the change?

bigbluehat: Looks like some validation errors.

gkellogg: I think it's good to go
… and I plan to make similar ones in the other specs
… so once we get the validation error fixed, we can merge this and make the others

bigbluehat: do we need to synchronize those changes across the specs?

gkellogg: the json-ld-commons repository is where the term changes would happen
… and then that would be copied back out to the individual spec repos
… and if we don't, then the github action will complain
… pchampin can you look at the markup issues?

pchampin: yep

---

[pchampin]

@gkellogg I actually don't see any markup issue there; the only reported issue is the inconsistency of the common files between the different repos, which is to be expected.

[gkellogg]

@gkellogg I actually don't see any markup issue there; the only reported issue is the inconsistency of the common files between the different repos, which is to be expected.

Great. The thing to do is to update json-ld-common with the change to the common files. After that is merged, this should build cleanly. We'll need to do similar updates to common files in other repos, and possibly rebase some open PRs.