Add guidelines for spdxId URI

[bact]

Heavily copied from https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#65-spdx-document-namespace-field

To fix spdx/spdx-spec#1326

Previous relevant discussions:

• Unrealistic spdxIds in Example spdx-spec#1323
• Add UUID to spdxIds in example data spdx-spec#1325

[bact]

@kzantow @augelu-tng is this SPDX document namespace and element URIs pattern align with what you use currently?

[augelu-tng]

In our case we have very large documents. Our goal was therefore to keep the spdxId as short as possible. At the moment we use the following format:
[Prefix]:[UUID]/[DocumentName]/[SequenceNumber]
where prefix defaults to urn:spdx.dev and DocumentName is one of source, build, or output.
All three documents describe artifacts within the same kernel build and thus share the same UUID.
For example:

• urn:spdx.dev:17fbbbad-b3a2-5a13-9558-00e25f843ee9/source/13
• urn:spdx.dev:17fbbbad-b3a2-5a13-9558-00e25f843ee9/build/42
• urn:spdx.dev:17fbbbad-b3a2-5a13-9558-00e25f843ee9/output/42

With a custom JSON-LD context this allows to have very short spdxIds in the document:

{
    "@context": [
        "https://spdx.org/rdf/3.0.1/spdx-context.jsonld",
        {
            "o": "urn:spdx.dev:17fbbbad-b3a2-5a13-9558-00e25f843ee9/output/"
        }
    ],
    "@graph": [
        {
            "spdxId": "o:0",
        }
    ]
}

[kzantow]

This change seems to align with my current usage. 👍

Specifically: if the user doesn't explicitly specify a document URI, I'm following the the 2.3 guidance to generate one, e.g. https://spdx.org/spdxdocs/<uuid>. Additionally, I've currently implemented compaction of element URIs using the namespace map, which I've seen to significantly improve both readability and size of the documents. In other words, elements other than the SpdxDocument have IDs generated with <prefix>: followed by <type-name>-<number> which would expand to the <SpdxDocument ID> + # + <type-name>-<number> . For example: SPDXRef:AiPackage-1, where SPDXRef has a namespace map entry for the URI https://spdx.org/spdxdocs/<uuid>#. These documents seem to validate properly but because the JSONLD context is not used but rather the namespace map, the IDs are not automatically expanded.

[kzantow]

One note: @augelu-tng using a custom LD context is not allowed by the spec for SPDX JSON. I am strongly in favor of leaning in to JSON LD here, as without it extensions have to be in fully expanded form, which is very large and difficult to read, but the spec is specific about using "@context": "https://spdx.org/rdf/3.0.1/spdx-context.jsonld".

[bact]

but the spec is specific about using "@context": "https://spdx.org/rdf/3.0.1/spdx-context.jsonld".

@kzantow we currently have a very long discussion about that at spdx/spdx-spec#1312

[augelu-tng]

@kzantow It should be allowed already. The spec says: "Additional namespace mappings may be defined within a separate object within the context.".
However, tooling does not support this currently.
See also spdx/tools-java#263 (comment)

[goneall]

Discussed on 10 Feb tech call - agreed we don't need to tie this to a specific release milestone

[goneall]

LGTM - I was thinking we may want to reference the namespaceMap as a way to create shorter ID's in the serialized document. However, this may over complicate the suggestions.

[maxhbr]

Looks good. But I would suggest to have something like spdx.docs as a fallback domain suggested for projects that do not want to set a default.

[bact]

From @maxhbr :

Looks good. But I would suggest to have something like spdx.docs as a fallback domain suggested for projects that do not want to set a default.

You mean using spdx.docs instead of spdx.org?

So instead of

https://spdx.org/spdxdocs/spdx-tools-v2.0.4-a0b427e6-9427-414c-9acc-d6e7c3a0d205

it will be

https://spdx.docs/spdx-tools-v2.0.4-a0b427e6-9427-414c-9acc-d6e7c3a0d205

I like the idea. It will make the ID a bit shorter.
(None of the URLs can be resolved anyway).

From @goneall :

LGTM - I was thinking we may want to reference the namespaceMap as a way to create shorter ID's in the serialized document. However, this may over complicate the suggestions.

We can do that. I think in terms of tooling, we are near to support that soon (from what I understand from the Go side and the shacl2code side). Suggesting a shorter ID will greatly improve file size and benefit everyone.

For now, with two approvals, I will merge this PR as it is. And we can improve the spdxId description (suggested domain + shorter ID + @kzantow's suggested <SpdxDocument ID> + # + <type-name>-<number> pattern for Element's spdxId) in another PR.

[bact]

spdx.docs domain name is taken. Whois information is not available, however.

[bact]

I open another issue here #1223 to document suggestions being made here and during the 17 Feb 2026 Tech call.