JSON-LD serialization: Recommend putting NamespaceMap at the root level and the beginning of the file

[bact]

From 14 Jan 2026 Implementers call, regarding the processing of JSON-LD namespaces, we would like to propose a specification update. This change aims to support one-pass streaming and the handling of large SPDX documents.

We propose that nodes containing namespace mapping information be located at the root level (structurally) and the beginning of the file (sequentially):

• @context (JSON-LD native)
• NamespaceMap (SPDX 3 mechanism)

While strongly recommended, this is not a strict requirement, as some SPDX producers cannot easily control the output order.

This ordering preference may be extended to type / @type within a node, as early placement helps the processor identify the node's schema more efficiently.

A natural location for this recommendation is the 'Serializations' section of the specification:
https://github.com/spdx/spdx-spec/blob/develop/docs/serializations.md
(the spec already requires that "a reference to the SPDX global context file at the top level" but the text may not be extended to other contexts).

[bact]

As NamespaceMap is inside SpdxDocument.namespaceMap, we may like to put SpdxDocument at the top as well.

Probably also along the ExternalMap from SpdxDocument.import.

https://spdx.github.io/spdx-spec/v3.0.1/model/Core/Classes/SpdxDocument/

[bact]

Recommended at root-level (from tree perspective) and at first lines (sequential reading) in the JSON-LD data:

1. Native JSON-LD @context
2. @graph containing serialized SPDX data

Recommended first nodes in @graph:

1. The SpdxDocument*
   • Contains information like profileConformance, import, namespaceMap, rootElement
2. The creationInfo (CreationInfo) of the SpdxDocument (1)
   • If not already inlined in (1)**
   • Contains information like specVersion, createdBy
   • Will be heavily referenced to by other nodes
3. The namespaceMap (list of NamespaceMap) of the SpdxDocument (1)
   • If not already inlined in (1)**
4. The import (list of ExternalMap) of the SpdxDocument (1)
   • If not already inlined in (1)**
5. The rootElement (Element) of the SpdxDocument (1)
   • Can be a Bom or a software_Sbom
6. The rootElement (Element) of (5), if (5) is Bom (or one of its subclasses)
   • Tend to be a Bom or one of its subclasses
   • If it is a software_Sbom, contains software_sbomType

*"A serialization must not contain more than one SpdxDocument." https://spdx.github.io/spdx-spec/v3.0.1/serializations/)
**May need to update the inlining rules spdx/spdx-3-model#1104

Possible JSON-LD data will look like (note that @id/spdxId and @type/type are also put up at the top of each node as well, hopefully assisting the parser):

{
    "@context": "https://spdx.org/rdf/3.1/spdx-context.jsonld",
    "@graph": [
        {
            "spdxId": "https://spdx.org/spdxdocs/0123",
            "type": "SpdxDocument",
            "profileConformance": [ "..." ],  # ProfileIdentifierType enum (string):
                                              # may need this early to assist profiel conformance test?
                                              # For example, abort immediately if the profile is not supported.
            "creationInfo": "_:creationinfo"
            "namespaceMap": [ "..." ]         # NamespaceMap: We need this early -- main point of this issue #1339
            "import": [ "..." ],              # ExternalMap: We need this early
            "rootElement": [ "https://spdx.org/spdxdocs/0123#software_Sbom_1" ],
            "dataLicense": "...",             # /SimpleLicensing/AnyLicenseInfo/
        },
        {
            "@id": "_:creationinfo",    # Need this early since it will get referenced a lot
            "type": "CreationInfo",
            "specVersion": "3.1"
            "created": "...",           # DateTime
            "createdBy": [ "..." ],     # Agent (do we also like to have this early?)
            "createdUsing": [ "..." ]   # Tool (do we also like to have this early?)
        },
        {
            "spdxId": "...",
            "type" : "NamespaceMap",
            "prefix" : "...",
            "namespace" : "..."
        },
        {
            "spdxId": "...",
            "type": "ExternalMap",
            "externalSpdxId": "urn:uuid:...",
            "locationHint": "https://..."
        },
        {
            "spdxId": "https://spdx.org/spdxdocs/0123#software_Sbom_1",
            "type": "software_Sbom",
            "software_sbomType": [ "..." ], # SbomType enum (string):
                                            # will it be useful to know this early?
                                            # For example, abort immediately if the SBOM type is not supported.
            "rootElement": [ "..." ],       # Element:
                                            # Do we also like to have this Element at the top?
                                            # (tend to be a software_Package or its subclasses)
                                            # What about the `hasConcludedLicense` and `hasDeclaredLicense` relationships of the package?
            "creationInfo": "_:creationinfo",
        },
   ...

[bact]

@augelu-tng @kzantow @pmonks @JPEWdev Will the suggested first nodes in #1339 (comment) help your use cases?

[augelu-tng]

Yes, I think that ordering makes sense. In my tool, I already follow this exact order, with the exception that createdBy (Agent) and createdUsing (Tool) are defined at the top level alongside the CreationInfo object. Moving them further down would not be a problem if that is the recommended structure.

Regarding the JSON-LD context, that would mean the top-level @context should be defined exclusively as the SPDX context https://spdx.org/rdf/3.1/spdx-context.jsonld and any additional mappings would be defined in SpdxDocument.NamespaceMap. That approach works for me, and I can update my tool accordingly.

[bact]

Will bring this to the next Implementers call.

[JPEWdev]

The namespace map needs to be in the @context in order for the document to be correctly parsed by any RDF parser. Therefore, this basically has the same rules as the rootElement/@graph. Specifically:

NamespaceMap properties should be encoded using the native serialization context if one exists. For example, the JSON-LD @context property.

[goneall]

From the implementer's call on 11 Feb 2026, we should use the @context to capture the namespaceMap and not use the namespaceMap property of the SPDX document. This would allow for JSON-LD parsers to properly utilize the map.

When deserializing, tools may copy the @context mapping values to the SPDX document namespaceMap to track the mappings.

[bact]

From the implementer's call on 11 Feb 2026, we should use the @context to capture the namespaceMap and not use the namespaceMap property of the SPDX document. This would allow for JSON-LD parsers to properly utilize the map.

When deserializing, tools may copy the @context mapping values to the SPDX document namespaceMap to track the mappings.

Does this mean, in a JSON-LD serialization of SPDX 3, we should not expect to see any NamespaceMap object?

[kzantow]

My only request is that this is clearly documented in the spec in the JSON serialization section -- I believe this is not exclusive to JSON-LD, so it should be clear it applies to both JSON serializations. The way I read the spec today indicates @context must be a single string pointing to the SPDX context URL. The spec should also be clear about exactly what constructs are allowed, such as no @vocab. Apologies if I've missed some suggested wording. It could be useful to add implementor note: if @context namespaces are used, these should be transitioned to a document-level NamespaceMap to preserve the mappings and what to do if the document already contains conflicting entries in a NamespaceMap.

I know this isn't exactly the same issue, but there should be similar documentation about the implicit behavior that all Elements in the @graph should be added to the SPDXDocument's element property with similar information about what to do if the document contains entries already (mentioned above with reference incorrectly to rootElement). It seems these would be related updates to clarify correct behavior for implementors.

If there are some objections to having implementor information in the spec, at least some references to that information would be greatly appreciated.

[goneall]

Does this mean, in a JSON-LD serialization of SPDX 3, we should not expect to see any NamespaceMap object?

I think so, however, it isn't clear in the spec what happens if there is a NamespaceMap in the SPDX document.

Per @kzantow comment above, we should make this very specific.

For both the element and namespaceMap property I can think of 3 ways to handle the overlap of the property and serialization. In all cases, we should state that the preferred method is to use JSON-LD @context and @graph.

1. Disallow the use of the namespaceMap and element - in the SPDX document if it is included in the SpdxDocument. The presences of these properties would be a validation error.
2. Ignore any values in the namespaceMap and element properties for JSON-LD serializations. It would not be an error. Tools could generate a warning.
3. Merge the 2 lists (e.g. merge the namespaceMap with the prefixes listed in the @context)
4. Have the properties in the SpdxDocument take precedence.

My preference is for 2 above. I definitely do not want to support 3 or 4, but I'm open to supporting 1.

In any case, we should document whatever approach we decide to take.

[kzantow]

I would prefer not to require an error -- we see many questionable SBOMs and try our best to handle them in our tooling and I'd rather not go against the spec. 2 or 4 seem like the best options to me to avoid possibly confusing or unexpected behavior with 3.

[JPEWdev]

I think my preference would be that implementations can choose if they want to deal with it, but validators will fail if they see it (for the specific reason that if someone doesn't put the namespaceMap in the @context, it won't "just work" with an RDF parser).

[bact]

Once we agreed on the requirement (ISO shall) / recommendation (ISO should), which SPDX spec version do we like to see this in?

1. 3.0.2
2. 3.1

or both.