Skip to content
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.

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

NamespaceMap: fix TODO; "ElementID" -> "Element ID" #821

Merged
merged 11 commits into from
Aug 9, 2024
5 changes: 3 additions & 2 deletions model/Core/Classes/ExternalMap.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,12 @@ SPDX-License-Identifier: Community-Spec-1.0

## Summary

A map of Element identifiers that are used within a Document but defined external to that Document.
A map of Element identifiers that are used within a Document but defined
external to that Document.

## Description

An External Map is a map of Element identifiers that are used within a Document
An external map is a map of Element identifiers that are used within a Document
but defined external to that Document.
The external map provides details about the externally-defined Element
such as its provenance, where to retrieve it, and how to verify its integrity.
Expand Down
58 changes: 29 additions & 29 deletions model/Core/Classes/NamespaceMap.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,45 +8,45 @@ A mapping between prefixes and namespace partial URIs.

## Description

A namespace map allows the creator of a collection of Elements that could be
serialized to suggest a set of shorter identifiers ("prefixes") for particular
namespace portions of ElementIDs to be used in SPDX content serialization in
order to provide a more human-readable and smaller serialized representation of
the Elements.
A namespace map allows the creator of a collection of serializable Elements
to suggest shorter identifiers ("prefixes") for specific namespace portions
of Element IDs. This map is used in SPDX content serialization to provide
a more human-readable and smaller serialized representation of the Elements.

For details of how NamespaceMap content is to be serialized please refer to
general SPDX serialization guidance at
<https://github.com/spdx/spdx-3-model/blob/main/serialization/README.md>
and the various serialization format specific .md filed under
<https://github.com/spdx/spdx-3-model/tree/main/serialization>
(TODO: update the URLs as soon as the context is publicly available)
the [Model and serializations](../../../docs/serializations.md) clause
and the various serialization format-specific files within the
[spdx-3-model repository](https://github.com/spdx/spdx-3-model/tree/main/serialization).

Namespace maps support a variety of relevant use cases such as:

1. An SPDX content producer wishing to provide clarity of their serialization
of an SPDX 2.X simple style collection where all content is newly minted and
a single prefix-namespace is used. The consumer of SPDX content wishes to
preserve the name space mapping provided by such a producer. In this case,
the consumer would record the namespace map prefixes in the NamespaceMap such
that subsequent serializations could reproduce the prefixes / namespaces in
the native serialization format.
of an SPDX 2.X simple style collection where all content is newly minted
and a single prefix-namespace is used. The consumer of SPDX content wishes
to preserve the name space mapping provided by such a producer.

In this case, the consumer would record the namespace map prefixes in the
NamespaceMap such that subsequent serializations could reproduce the
prefixes / namespaces in the native serialization format.

2. An SPDX content producer wishing to maintain consistent prefix use and
understanding across multiple different serialization formats of the produced
content.
For example, an SBOM producer wishes to share/publish the SBOM as JSON-LD and
XML. The producer can specify the preferred prefix mappings in the native
serialization format using information from a single Namespacemap accessible
local to the producer.
understanding across multiple different serialization formats of the
produced content.

For example, an SBOM producer wishes to share/publish the SBOM as JSON-LD
and XML. The producer can specify the preferred prefix mappings in the
native serialization format using information from a single NamespaceMap
accessible local to the producer.

3. An SPDX content consumer/producer wishing to maintain consistent prefix use
while round tripping from SPDX content received, deserialized,
modified/extended in some way, and then reserialized in the same
serialization form.
In this case the prefix-namespace mappings utilized in the content are
transformed from the original native namespace/prefix into the in memory
NamespaceMap then transformed from the NamespaceMap back into the resultant
serialization native namespace / prefix format.
while round tripping from SPDX content received, deserialized,
modified/extended in some way, and then reserialized in the same
serialization form.

In this case the prefix-namespace mappings utilized in the content are
transformed from the original native namespace/prefix into the in memory
NamespaceMap then transformed from the NamespaceMap back into the resultant
serialization native namespace / prefix format.

## Metadata

Expand Down
4 changes: 2 additions & 2 deletions model/Core/Properties/namespace.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,12 @@ SPDX-License-Identifier: Community-Spec-1.0
## Summary

Provides an unambiguous mechanism for conveying a URI fragment portion of an
ElementID.
Element ID.

## Description

A namespace provides an unambiguous mechanism for conveying a URI fragment
portion of an ElementID.
portion of an Element ID.

## Metadata

Expand Down