From 970525b266d2d4a2625b0b8bd1ecfc7a257d877f Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Fri, 9 Aug 2024 18:52:14 +0100 Subject: [PATCH] NamespaceMap: fix TODO; "ElementID" -> "Element ID" (#821) * Remove TODO and fix caps Signed-off-by: Arthit Suriyawongkul * Use named link Also use 4-space indent for bullet list, to keep the multiple paragraphs rendered correctly. Signed-off-by: Arthit Suriyawongkul * Point to HTML version of serialization instead of GitHub repo Signed-off-by: Arthit Suriyawongkul * Update model/Core/Classes/NamespaceMap.md Co-authored-by: Alexios Zavras (zvr) Signed-off-by: Arthit Suriyawongkul * Update model/Core/Classes/NamespaceMap.md Co-authored-by: Alexios Zavras (zvr) Signed-off-by: Arthit Suriyawongkul * "ElementID" -> "Element ID" Small grammar revision ElementID is not a specific name anywhere in the model (possibly an externalSpdxId ?) Signed-off-by: Arthit Suriyawongkul * "External Map" -> "external map" Signed-off-by: Arthit Suriyawongkul --------- Signed-off-by: Arthit Suriyawongkul Co-authored-by: Alexios Zavras (zvr) --- model/Core/Classes/ExternalMap.md | 5 +-- model/Core/Classes/NamespaceMap.md | 58 +++++++++++++++--------------- model/Core/Properties/namespace.md | 4 +-- 3 files changed, 34 insertions(+), 33 deletions(-) diff --git a/model/Core/Classes/ExternalMap.md b/model/Core/Classes/ExternalMap.md index 43e6644d9..464a4ad30 100644 --- a/model/Core/Classes/ExternalMap.md +++ b/model/Core/Classes/ExternalMap.md @@ -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. diff --git a/model/Core/Classes/NamespaceMap.md b/model/Core/Classes/NamespaceMap.md index ac9aacb13..00382de81 100644 --- a/model/Core/Classes/NamespaceMap.md +++ b/model/Core/Classes/NamespaceMap.md @@ -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 - -and the various serialization format specific .md filed under - -(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 diff --git a/model/Core/Properties/namespace.md b/model/Core/Properties/namespace.md index b7699f92d..901f6475c 100644 --- a/model/Core/Properties/namespace.md +++ b/model/Core/Properties/namespace.md @@ -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