You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@sourcelume.apache.org by jgoodyear <jg...@apache.org> on 2026/10/11 09:43:51 UTC
[DISCUSS] Canonical IRI for the Sourcelume JSON-LD context, and pinning it
Hi all,
While reviewing registry PR #3 (record validation) and PR #5 (async ingest), I
noticed a gap in the spec that I'd like us to settle before we cut 0.0.1.
https://github.com/apache/sourcelume-registry/pull/3
https://github.com/apache/sourcelume-registry/pull/5
The gap: the spec defines the JSON-LD context file
(context/0.0.1/sourcelume.jsonld) but never states the one absolute IRI that
records should use to reference it. The JSON Schema already has an absolute
$id (https://sourcelume.apache.org/schema/0.0.1/sourcelume.schema.json), and
the natural counterpart would be
https://sourcelume.apache.org/context/0.0.1/sourcelume.jsonld. One of our own
tests already uses that string, but nothing declares it canonical, the schema
accepts any @context, and I don't believe anything is hosted at that URL yet.
Why it matters for the PRs:
- PR #3 keeps validation offline, so it never fetches remote contexts. As
described in the PR, it substitutes the bundled spec context for any
reference that ends with the context's resource path, because there is no
canonical IRI to match exactly. That is safe against SSRF, but it means a
URL on any host ending in that path is treated as ours.
- PR #5 stores each record's JSON-LD byte for byte so we can verify
signatures later. A signed record that points at a context by URL only
means the same thing tomorrow if the content at that URL never changes.
Why pinning matters: a signature covers the bytes of the record, including
the pointer to its context. If the content behind that pointer can change,
the meaning of an already-signed record can change without any byte of the
record changing. Ecosystems that sign JSON-LD, such as Verifiable Credentials,
generally treat context pinning as essential. For us that means published
context versions should be immutable, and we may want to consider pinning by
digest once Attest exists.
A related inconsistency: the sl: prefix expands to
https://sourcelume.apache.org/ns/0.0.1#, but the spec prose gives the
agreement-supplied license IRI as
https://sourcelume.apache.org/ns#agreement-supplied,
which is a different namespace.
Questions for the list:
1. Should https://sourcelume.apache.org/context/0.0.1/sourcelume.jsonld be the
canonical context IRI, and can we host it, served as application/ld+json
and never modified after release?
2. Should the sl: namespace be versioned (/ns/0.0.1#) or stable (/ns#)? With
versioning, sl:ProvenanceRecord in 0.0.1 and 0.0.2 are different IRIs.
3. Should the JSON Schema constrain @context, for example to the canonical IRI
or an inline object, rather than accepting anything?
4. Which form should the agreement-supplied IRI take once (2) is decided?
Since released spec versions are immutable, these are best settled before the
0.0.1 vote. Once we agree, the registry can move from suffix matching to an
exact match.
Thoughts welcome, especially from anyone who has pinned contexts in signed
JSON-LD before.
Thanks,
Jamie
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@sourcelume.apache.org
For additional commands, e-mail: dev-help@sourcelume.apache.org
Re: [DISCUSS] Canonical IRI for the Sourcelume JSON-LD context, and pinning it
Posted by Achim Nierbeck via dev <de...@sourcelume.apache.org>.
Hi Jamie,
agreed on your four answers as written:
- canonical context IRI
https://sourcelume.apache.org/context/0.0.1/sourcelume.jsonld,
served as application/ld+json and never modified after release
- stable namespace https://sourcelume.apache.org/ns#, versioned context URL
- strict @context: only the canonical IRI, no inline variant for 0.0.1
- agreement-supplied as https://sourcelume.apache.org/ns#agreement-supplied
Both repos have PRs for this:
- sourcelume-spec #8: pins @context to the canonical IRI in the JSON
Schema, moves sl: to /ns#, and makes tools/validate.py resolve the
context from the bundled copy.
- sourcelume-registry #3: the SHACL validator now matches the canonical
IRI exactly instead of by path suffix. Relative references and other
hosts with the same path are refused.
Salmas review of the spec on Slack asked
about content created over a period, and I took that one into #8 as a
separate commit, so it is easy to drop if you don't want it: an
optional contentCreatedEnd next to contentCreated. contentCreated stays
the start of the period, so existing records stay valid, and SHACL
rejects an end before the start.
The same review raised more points. I'd like to discuss them in this
thread before the vote, since each changes the context:
- origin as machine-readable IRI next to the free text
- a small recommended vocabulary for custodyChain.action
- license as a structured object (scope, category, note, history)
- dct: vs. schema: for identifier and license in the Croissant crosswalk
- added optional for standalone datasets
regards,
Achim
Am So., 11. Okt. 2026 um 12:38 Uhr schrieb Jamie G. <
jamie.goodyear@gmail.com>:
> My take on the questions:
>
> 1. I believe we should adopt
> https://sourcelume.apache.org/context/0.0.1/sourcelume.jsonld as the
> canonical IRI and host it immutably with Content-Type:
> application/ld+json. It'll help make our ecosystem predictable, and
> help keep integrity for validators.
>
> 2. Use a stable core namespace (https://sourcelume.apache.org/ns#),
> while keeping the context URL versioned
> (/context/0.0.1/sourcelume.jsonld). This will help as each time we
> release we won't be having to touch so many mappings downstream.
>
> 3. Strictly constrain @context in the JSON Schema to allow only the
> canonical IRI (or an exact inline match).
>
> If we do not do this I fear that we could have semantic divergence or
> worse fraud. Allowing arbitrary @context payloads permits records
> where raw JSON attributes diverge from expanded RDF assertions (such
> as remapping license to an unvalidated predicate). Part of our mission
> is to provide some amount more trust in our data, keeping vectors for
> mis-representation to a minimum should be our standard operating
> procedure.
>
> 4. Set the agreement-supplied license IRI to
> https://sourcelume.apache.org/ns#agreement-supplied.
>
> Aligning this identifier with the stable namespace chosen in Question
> 2 eliminates discrepancies between specification prose, ontology
> definitions, and code implementations. Having a single namespace also
> just makes things easier to grok.
>
> --Jamie
>
> On Sun, Oct 11, 2026 at 7:13 AM jgoodyear <jg...@apache.org> wrote:
> >
> > Hi all,
> >
> > While reviewing registry PR #3 (record validation) and PR #5 (async
> ingest), I
> > noticed a gap in the spec that I'd like us to settle before we cut 0.0.1.
> >
> > https://github.com/apache/sourcelume-registry/pull/3
> > https://github.com/apache/sourcelume-registry/pull/5
> >
> >
> > The gap: the spec defines the JSON-LD context file
> > (context/0.0.1/sourcelume.jsonld) but never states the one absolute IRI
> that
> > records should use to reference it. The JSON Schema already has an
> absolute
> > $id (https://sourcelume.apache.org/schema/0.0.1/sourcelume.schema.json),
> and
> > the natural counterpart would be
> > https://sourcelume.apache.org/context/0.0.1/sourcelume.jsonld. One of
> our own
> > tests already uses that string, but nothing declares it canonical, the
> schema
> > accepts any @context, and I don't believe anything is hosted at that URL
> yet.
> >
> > Why it matters for the PRs:
> >
> > - PR #3 keeps validation offline, so it never fetches remote contexts. As
> > described in the PR, it substitutes the bundled spec context for any
> > reference that ends with the context's resource path, because there is
> no
> > canonical IRI to match exactly. That is safe against SSRF, but it
> means a
> > URL on any host ending in that path is treated as ours.
> > - PR #5 stores each record's JSON-LD byte for byte so we can verify
> > signatures later. A signed record that points at a context by URL only
> > means the same thing tomorrow if the content at that URL never changes.
> >
> > Why pinning matters: a signature covers the bytes of the record,
> including
> > the pointer to its context. If the content behind that pointer can
> change,
> > the meaning of an already-signed record can change without any byte of
> the
> > record changing. Ecosystems that sign JSON-LD, such as Verifiable
> Credentials,
> > generally treat context pinning as essential. For us that means published
> > context versions should be immutable, and we may want to consider
> pinning by
> > digest once Attest exists.
> >
> > A related inconsistency: the sl: prefix expands to
> > https://sourcelume.apache.org/ns/0.0.1#, but the spec prose gives the
> > agreement-supplied license IRI as
> > https://sourcelume.apache.org/ns#agreement-supplied,
> > which is a different namespace.
> >
> > Questions for the list:
> >
> > 1. Should https://sourcelume.apache.org/context/0.0.1/sourcelume.jsonld
> be the
> > canonical context IRI, and can we host it, served as
> application/ld+json
> > and never modified after release?
> >
> > 2. Should the sl: namespace be versioned (/ns/0.0.1#) or stable (/ns#)?
> With
> > versioning, sl:ProvenanceRecord in 0.0.1 and 0.0.2 are different IRIs.
> >
> > 3. Should the JSON Schema constrain @context, for example to the
> canonical IRI
> > or an inline object, rather than accepting anything?
> >
> > 4. Which form should the agreement-supplied IRI take once (2) is decided?
> >
> > Since released spec versions are immutable, these are best settled
> before the
> > 0.0.1 vote. Once we agree, the registry can move from suffix matching to
> an
> > exact match.
> >
> > Thoughts welcome, especially from anyone who has pinned contexts in
> signed
> > JSON-LD before.
> >
> > Thanks,
> > Jamie
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@sourcelume.apache.org
> For additional commands, e-mail: dev-help@sourcelume.apache.org
>
>
--
Apache Member
Apache Karaf <http://karaf.apache.org/> Committer & PMC
OPS4J Pax Web <http://wiki.ops4j.org/display/paxweb/Pax+Web/> Committer &
Project Lead
blog <http://notizblog.nierbeck.de/>
Co-Author of Apache Karaf Cookbook <http://bit.ly/1ps9rkS>
Re: [DISCUSS] Canonical IRI for the Sourcelume JSON-LD context, and pinning it
Posted by "Jamie G." <ja...@gmail.com>.
My take on the questions:
1. I believe we should adopt
https://sourcelume.apache.org/context/0.0.1/sourcelume.jsonld as the
canonical IRI and host it immutably with Content-Type:
application/ld+json. It'll help make our ecosystem predictable, and
help keep integrity for validators.
2. Use a stable core namespace (https://sourcelume.apache.org/ns#),
while keeping the context URL versioned
(/context/0.0.1/sourcelume.jsonld). This will help as each time we
release we won't be having to touch so many mappings downstream.
3. Strictly constrain @context in the JSON Schema to allow only the
canonical IRI (or an exact inline match).
If we do not do this I fear that we could have semantic divergence or
worse fraud. Allowing arbitrary @context payloads permits records
where raw JSON attributes diverge from expanded RDF assertions (such
as remapping license to an unvalidated predicate). Part of our mission
is to provide some amount more trust in our data, keeping vectors for
mis-representation to a minimum should be our standard operating
procedure.
4. Set the agreement-supplied license IRI to
https://sourcelume.apache.org/ns#agreement-supplied.
Aligning this identifier with the stable namespace chosen in Question
2 eliminates discrepancies between specification prose, ontology
definitions, and code implementations. Having a single namespace also
just makes things easier to grok.
--Jamie
On Sun, Oct 11, 2026 at 7:13 AM jgoodyear <jg...@apache.org> wrote:
>
> Hi all,
>
> While reviewing registry PR #3 (record validation) and PR #5 (async ingest), I
> noticed a gap in the spec that I'd like us to settle before we cut 0.0.1.
>
> https://github.com/apache/sourcelume-registry/pull/3
> https://github.com/apache/sourcelume-registry/pull/5
>
>
> The gap: the spec defines the JSON-LD context file
> (context/0.0.1/sourcelume.jsonld) but never states the one absolute IRI that
> records should use to reference it. The JSON Schema already has an absolute
> $id (https://sourcelume.apache.org/schema/0.0.1/sourcelume.schema.json), and
> the natural counterpart would be
> https://sourcelume.apache.org/context/0.0.1/sourcelume.jsonld. One of our own
> tests already uses that string, but nothing declares it canonical, the schema
> accepts any @context, and I don't believe anything is hosted at that URL yet.
>
> Why it matters for the PRs:
>
> - PR #3 keeps validation offline, so it never fetches remote contexts. As
> described in the PR, it substitutes the bundled spec context for any
> reference that ends with the context's resource path, because there is no
> canonical IRI to match exactly. That is safe against SSRF, but it means a
> URL on any host ending in that path is treated as ours.
> - PR #5 stores each record's JSON-LD byte for byte so we can verify
> signatures later. A signed record that points at a context by URL only
> means the same thing tomorrow if the content at that URL never changes.
>
> Why pinning matters: a signature covers the bytes of the record, including
> the pointer to its context. If the content behind that pointer can change,
> the meaning of an already-signed record can change without any byte of the
> record changing. Ecosystems that sign JSON-LD, such as Verifiable Credentials,
> generally treat context pinning as essential. For us that means published
> context versions should be immutable, and we may want to consider pinning by
> digest once Attest exists.
>
> A related inconsistency: the sl: prefix expands to
> https://sourcelume.apache.org/ns/0.0.1#, but the spec prose gives the
> agreement-supplied license IRI as
> https://sourcelume.apache.org/ns#agreement-supplied,
> which is a different namespace.
>
> Questions for the list:
>
> 1. Should https://sourcelume.apache.org/context/0.0.1/sourcelume.jsonld be the
> canonical context IRI, and can we host it, served as application/ld+json
> and never modified after release?
>
> 2. Should the sl: namespace be versioned (/ns/0.0.1#) or stable (/ns#)? With
> versioning, sl:ProvenanceRecord in 0.0.1 and 0.0.2 are different IRIs.
>
> 3. Should the JSON Schema constrain @context, for example to the canonical IRI
> or an inline object, rather than accepting anything?
>
> 4. Which form should the agreement-supplied IRI take once (2) is decided?
>
> Since released spec versions are immutable, these are best settled before the
> 0.0.1 vote. Once we agree, the registry can move from suffix matching to an
> exact match.
>
> Thoughts welcome, especially from anyone who has pinned contexts in signed
> JSON-LD before.
>
> Thanks,
> Jamie
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@sourcelume.apache.org
For additional commands, e-mail: dev-help@sourcelume.apache.org