From 1f143550601c27a12014a8cb1c06a85210cc7476 Mon Sep 17 00:00:00 2001 From: Alexios Zavras Date: Sun, 11 Aug 2024 16:24:11 +0200 Subject: [PATCH 1/4] Removes numbering from chapters/sections in main spec Signed-off-by: Alexios Zavras --- docs/conformance.md | 38 +++++++++++++++++------------------ docs/references.md | 6 +++--- docs/scope.md | 2 +- docs/serializations.md | 10 ++++----- docs/symbols.md | 2 +- docs/terms-and-definitions.md | 2 +- 6 files changed, 30 insertions(+), 30 deletions(-) diff --git a/docs/conformance.md b/docs/conformance.md index 76ac8e56e4..d8e449229d 100644 --- a/docs/conformance.md +++ b/docs/conformance.md @@ -1,6 +1,6 @@ -# 5 Conformance +# Conformance -## 5.1 Alternate notation for some conformance requirements +## Alternate notation for some conformance requirements This standard contains more than a few cardinality assertions, each of which indicates absolute, optional, or conditional requirements. @@ -20,7 +20,7 @@ required, and if so, how many occurrences are required; also, whether a feature is permitted, and if so, in what number. As this is the format long familiar to the SPDX community, it has been preserved in this specification. -## 5.2 Introduction to Profiles +## Introduction to Profiles Profile is the term for a compliance point within the SPDX community across The Linux Foundation and OMG. The System Package Data Exchange (SPDX) specification @@ -37,7 +37,7 @@ defines the following six compliance points, defined as “Profiles”: The Core and Software Profiles are mandatory. All others are optional. -## 5.3 Core Profile compliance point +## Core Profile compliance point The Core Profile includes the definitions of classes properties and vocabularies usable by all SPDX profiles when producing or consuming SPDX @@ -55,7 +55,7 @@ This compliance point, in combination with the Software Profile compliance point, provides a baseline of functionality that facilitates interchange of the bills of materials information produced by tools supporting SPDX. -## 5.4 Software Profile compliance point +## Software Profile compliance point The Software Profile includes the definitions of classes, properties and vocabularies for refering to and conveying information about software and is @@ -74,7 +74,7 @@ This compliance point, in combination with the Core Profile compliance point, provides a baseline of functionality that facilitates interchange of the bills of materials information produced by tools supporting SPDX. -## 5.5 Security Profile compliance point +## Security Profile compliance point The Security Profile captures security-related information when producing or consuming SPDX content. @@ -95,7 +95,7 @@ SPDX. This compliance point facilitates interchange of the security information produced by tools supporting SPDX. -## 5.6 Licencing Profile compliance point +## Licencing Profile compliance point The Licensing Profile includes capturing details relevant to software licensing and intellectual property information when producing or consuming SPDX content. @@ -115,7 +115,7 @@ expressing which licenses and copyright notices are determined by persons or automated tooling to apply to distributions of software that are produced by tools supporting SPDX. -## 5.7 Dataset Profile compliance point +## Dataset Profile compliance point The Dataset Profile captures the relevant information about the datasets used in an AI system or other applications when producing or consuming SPDX content. @@ -138,7 +138,7 @@ of the SPDX. This compliance point facilitates interchange of the information about datasets produced by tools supporting SPDX. -## 5.8 AI Profile compliance point +## AI Profile compliance point The AI Profile captures an inventory list of software components and dependencies associated with an AI system when producing or consuming SPDX @@ -161,7 +161,7 @@ the SPDX. This compliance point facilitates interchange of the AI model related information produced by tools supporting SPDX. -## 5.9 Build Profile compliance point +## Build Profile compliance point The Build Profile captures build-related information when producing or consuming SPDX content. @@ -181,7 +181,7 @@ the SPDX. This compliance point facilitates interchange of the build information produced by tools supporting SPDX. -## 5.10 Lite Profile compliance point +## Lite Profile compliance point The Lite Profile captures the minimum set of information required for license compliance in the software supply chain for producing or consuming SPDX @@ -200,7 +200,7 @@ of the SPDX. This compliance point facilitates interchange of minimal licencing information when produced by tools supporting SPDX. -## 5.11 Extension Profile compliance point +## Extension Profile compliance point The Extension Profile captures extended tailored information when producing or consuming non-standard SPDX content in three ways: @@ -243,7 +243,7 @@ beyond the standard SPDX produced by tools supporting SPDX and is used between cooperating parties that understand the form of the extension and can produce and consume its non-standard content. -## 5.12 Standard data format requirements +## Standard data format requirements The data format specification and recommendations are subject to the following constraints: @@ -256,24 +256,24 @@ following constraints: - Multiple serialization formats may be used to represent the information being exchanged. Current supported formats include: - - **YAML 1.2** + - *YAML 1.2* see: [YAML Ain’t Markup Language (YAML™) version 1.2](https://yaml.org/spec/1.2/) - - **JavaScript Object Notation** (JSON) + - *JavaScript Object Notation* (JSON) see: [ECMA-404](https://ecma-international.org/publications-and-standards/standards/ecma-404/) - The JSON Schema for SPDX can be found in the [SPDX specification Git repository schemas directory](https://github.com/spdx/spdx-spec/blob/master/schemas/spdx-schema.json) - - **Resource Description Framework** (RDF, also referred to as RDF/XML) + - *Resource Description Framework* (RDF, also referred to as RDF/XML) see: [RDF 1.1 XML Syntax](https://www.w3.org/TR/rdf-syntax-grammar/) - - **tag:value** flat text file as described in this specification - - **.xls** spreadsheets + - *tag:value* flat text file as described in this specification + - *.xls* spreadsheets - In addition to the supported formats, the following format is in development with a plan to complete the specification in the next release: - - **Extensible Markup Language** (XML) + - *Extensible Markup Language* (XML) see: [Extensible Markup Language (XML) 1.0 (Fifth Edition)](https://www.w3.org/TR/2008/REC-xml-20081126/) diff --git a/docs/references.md b/docs/references.md index e3fd4a60a2..342d6d8cbd 100644 --- a/docs/references.md +++ b/docs/references.md @@ -1,6 +1,6 @@ -# 2 References +# References -## 2.1 Normative References +## Normative References The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated @@ -69,7 +69,7 @@ The Internet Society Network Working Group, *SPDX License Exceptions*, The Linux Foundation, [https://spdx.org/licenses/exceptions-index.html](https://spdx.org/licenses/exceptions-index.html) -## 2.2 Non-normative References +## Non-normative References The following documents are referred to in the text. diff --git a/docs/scope.md b/docs/scope.md index 71cbd44343..8ee8fc06e7 100644 --- a/docs/scope.md +++ b/docs/scope.md @@ -1,4 +1,4 @@ -# 1 Scope +# Scope The System Package Data Exchange (SPDX®) specification defines an open standard for communicating bill of materials (BOM) information for different topic diff --git a/docs/serializations.md b/docs/serializations.md index 5f5d664aea..1966ee94e6 100644 --- a/docs/serializations.md +++ b/docs/serializations.md @@ -1,6 +1,6 @@ -# 4 Model and serializations +# Model and serializations -## 4.1 Overview +## Overview This specification defines the data model of the SPDX standard, describing every piece of information about systems with software components. The data @@ -11,7 +11,7 @@ way to represent and exchange information. The data may be serialized in a variety of formats for storage and transmission. -## 4.2 RDF serialization +## RDF serialization Since the data model is based on RDF, any SPDX data can be serialized in any of the multiple RDF serialization formats, including but not limited to: @@ -30,7 +30,7 @@ The SPDX specification is accompanied by a that can be used to serialize SPDX in a much simpler and more human-readable JSON-LD format. -## 4.3 Canonical serialization +## Canonical serialization Canonical serialization is a single, consistent, normalized, deterministic, and reproducible form. @@ -66,7 +66,7 @@ with the following additional characteristics: value. A single comma separates a value from a following name. The name/value pairs are ordered by name. -## 4.4 Serialization information +## Serialization information A collection of elements may be serialized in multiple formats. diff --git a/docs/symbols.md b/docs/symbols.md index beede650c0..b9ce84ecee 100644 --- a/docs/symbols.md +++ b/docs/symbols.md @@ -1,4 +1,4 @@ -# 4 Symbols +# Symbols List of symbols/abbreviations. diff --git a/docs/terms-and-definitions.md b/docs/terms-and-definitions.md index be426fac8b..877c7a50fa 100644 --- a/docs/terms-and-definitions.md +++ b/docs/terms-and-definitions.md @@ -1,4 +1,4 @@ -# 3 Terms and definitions +# Terms and definitions To do: Need to fill this in to align to the terms and definitions that apply in this revision of the specification. From 2acae715e971f8b84da8ea85f93849bdcf89c5ab Mon Sep 17 00:00:00 2001 From: Alexios Zavras Date: Sun, 11 Aug 2024 17:59:07 +0200 Subject: [PATCH 2/4] Fixes the annexes Signed-off-by: Alexios Zavras --- docs/annexes/SPDX-Lite.md | 7 +- docs/annexes/SPDX-license-expressions.md | 22 +- docs/annexes/changes-from-previous-iso.md | 15 + docs/annexes/cross-reference.md | 247 ----- docs/annexes/diffs-from-previous-editions.md | 941 ------------------ docs/annexes/getting-started.md | 740 -------------- .../including-security-information-in-SPDX.md | 401 -------- ...cense-matching-guidelines-and-templates.md | 102 +- docs/annexes/pkg-url-specification.md | 38 +- ...-and-identifier-syntax.md => rdf-model.md} | 31 +- ...-SPDX-short-identifiers-in-source-files.md | 73 -- ...g-SPDX-to-comply-with-industry-guidance.md | 61 -- docs/bibliography.md | 7 - 13 files changed, 116 insertions(+), 2569 deletions(-) create mode 100644 docs/annexes/changes-from-previous-iso.md delete mode 100644 docs/annexes/cross-reference.md delete mode 100644 docs/annexes/diffs-from-previous-editions.md delete mode 100644 docs/annexes/getting-started.md delete mode 100644 docs/annexes/including-security-information-in-SPDX.md rename docs/annexes/{RDF-object-model-and-identifier-syntax.md => rdf-model.md} (50%) delete mode 100644 docs/annexes/using-SPDX-short-identifiers-in-source-files.md delete mode 100644 docs/annexes/using-SPDX-to-comply-with-industry-guidance.md delete mode 100644 docs/bibliography.md diff --git a/docs/annexes/SPDX-Lite.md b/docs/annexes/SPDX-Lite.md index f326241b54..17115f4b52 100644 --- a/docs/annexes/SPDX-Lite.md +++ b/docs/annexes/SPDX-Lite.md @@ -1,6 +1,6 @@ -# Annex H: SPDX Lite +# SPDX Lite -## H.1 Definition of the Lite profile +## Definition of the Lite profile The Lite profile is designed to make it quick and easy to start a Software Bill of Materials in situations where a company may have limited capacity for introducing new items into its process. The Lite profile captures the minimum set of information required for license compliance in the software supply chain. It contains information about the creation of the SBOM, package lists with licensing and other related items, and their relationships. @@ -8,11 +8,10 @@ The Lite profile captures the minimum set of information required for license co All elements in Lite profile are essential for complying with licenses. It is easy to use a SPDX document with the Lite profile for anyone who does not have enough knowledge about licensing information and easy to import license information from former versions of SPDX Lite format files. The Lite profile offers the flexibility to be used either alone or in combination with other SPDX profiles as a SPDX document in the software supply chain. -## H.2 Table of the Lite profile elements +## Table of the Lite profile elements A SPDX document with the Lite profile must include properties for each class listed in **Table H.1**. And ```Cardinality 1..``` means a **REQUIRED** element, and the others **SHOULD** be filled in as much as possible if necessary. -**Table H.1 — the Lite profile elements** 1. For a /Core/SpdxDocument to be conformant with this profile, the following has to hold: diff --git a/docs/annexes/SPDX-license-expressions.md b/docs/annexes/SPDX-license-expressions.md index eebc4dbee1..2371e22785 100644 --- a/docs/annexes/SPDX-license-expressions.md +++ b/docs/annexes/SPDX-license-expressions.md @@ -1,6 +1,6 @@ -# Annex D: SPDX license expressions (Normative) +# SPDX license expressions (Normative) -## D.1 Overview +## Overview Often a single license can be used to represent the licensing terms of a source code or binary file, but there are situations where a single license identifier is not sufficient. A common example is when software is offered under a choice of one or more licenses (e.g., GPL-2.0-only OR BSD-3-Clause). Another example is when a set of licenses is needed to represent a binary program constructed by compiling and linking two (or more) different source files each governed by different licenses (e.g., LGPL-2.1-only AND BSD-3-Clause). @@ -48,7 +48,7 @@ There MUST NOT be white space between a license-id and any following `+`. This s In the `tag:value` format, a license expression MUST be on a single line, and MUST NOT include a line break in the middle of the expression. -## D.2 Case sensitivity +## Case sensitivity License expression operators (`AND`, `and`, `OR`, `or`, `WITH` and `with`) should be matched in a *case-sensitive* manner, i.e., letters must be all upper case or all lower case. @@ -60,7 +60,7 @@ For user defined license identifiers, only the variable part (after `LicenseRef- The same applies to `AdditionRef-` user defined identifiers. -## D.3 Simple license expressions +## Simple license expressions A simple `` is composed one of the following: @@ -80,9 +80,9 @@ DocumentRef-spdx-tool-1.2:LicenseRef-MIT-Style-2 The current set of valid license identifiers can be found in [spdx.org/licenses](https://spdx.org/licenses). -## D.4 Composite license expressions +## Composite license expressions -### D.4.1 Introduction +### Introduction More expressive composite license expressions can be constructed using "OR", "AND", and "WITH" operators similar to constructing mathematical expressions using arithmetic operators. @@ -90,7 +90,7 @@ For the `tag:value` format, any license expression that consists of more than on Nested parentheses can also be used to specify an order of precedence which is discussed in more detail in [D.4.5](#D.4.5). -### D.4.2 Disjunctive "OR" operator +### Disjunctive "OR" operator If presented with a choice between two or more licenses, use the disjunctive binary "OR" operator to construct a new license expression, where both the left and right operands are valid license expression values. @@ -114,7 +114,7 @@ LGPL-2.1-only OR MIT OR BSD-3-Clause It is allowed to use the operator in lower case form `or`. -### D.4.3 Conjunctive "AND" operator +### Conjunctive "AND" operator If required to simultaneously comply with two or more licenses, use the conjunctive binary "AND" operator to construct a new license expression, where both the left and right operands are a valid license expression values. @@ -138,7 +138,7 @@ LGPL-2.1-only AND MIT AND BSD-2-Clause It is allowed to use the operator in lower case form `and`. -### D.4.4 Additive "WITH" operator +### Additive "WITH" operator Sometimes license texts are found with additional text, which might or might not modify the original license terms. @@ -157,7 +157,7 @@ The current set of valid license exceptions identifiers can be found in [spdx.or It is allowed to use the operator in lower case form `with`. -### D.4.5 Order of precedence and parentheses +### Order of precedence and parentheses The order of application of the operators in an expression matters (similar to mathematical operators). The default operator order of precedence of a `` a is: @@ -188,7 +188,7 @@ MIT AND (LGPL-2.1-or-later OR BSD-3-Clause) states the OR operator should be applied before the AND operator. That is, one should first select between the LGPL-2.1-or-later or the BSD-3-Clause license before applying the MIT license. -### D.4.6 License expressions in RDF +### License expressions in RDF A conjunctive license can be expressed in RDF via a `` element, with an spdx:member property for each element in the conjunctive license. Two or more members are required. diff --git a/docs/annexes/changes-from-previous-iso.md b/docs/annexes/changes-from-previous-iso.md new file mode 100644 index 0000000000..33d7589a9e --- /dev/null +++ b/docs/annexes/changes-from-previous-iso.md @@ -0,0 +1,15 @@ +# Changes from the previous version + +## Overview + +The previous published version of this standard was ISO/IEC 5962:2021(E), +titled "Information technology -- SPDX® Specification V2.2.1" +published by ISO (the International Organization for Standardization) +and IEC (the International Electrotechnical Commission) +in 2021. + +The present chapter outlines the changes that the current version +introduces related to that previous edition. + +## TODO: Kate to fill in ... + diff --git a/docs/annexes/cross-reference.md b/docs/annexes/cross-reference.md deleted file mode 100644 index 936fc2faa6..0000000000 --- a/docs/annexes/cross-reference.md +++ /dev/null @@ -1,247 +0,0 @@ -# Annex I: Cross referencing in SPDX 3 (Informative) - -This document will walk though how to refer to SPDX Elements across documents -(e.g. cross reference). - -If you do would like to construct the complete example documents from this -Markdown file, use the following command: - -```shell -cat cross-reference.md | awk 'BEGIN{flag=0} /^```json/, $0=="```" { if (/^---$/){flag++} else if ($0 !~ /^```.*/ ) print $0 > "doc-" flag ".spdx.json"}' -``` - -## Linking via spdxId - -It is frequently desired (and necessary) to reference an SPDX 3 -[Element][Class_Element] that lives in one document from another. Since SPDX -documents are valid [JSON-LD][JSON_LD] documents, linking elements together can -be as simple as referencing the spdxId of one element from another (in the same -way that doing so within a document links Elements together. For example, -assume we have this document that contains a [Person][Class_Person] we want to -reference in another document: - -```json -{ - "@context": "https://spdx.org/rdf/3.0.0/spdx-context.jsonld", - "@graph": [ - { - "type": "Person", - "spdxId": "https://spdx.org/spdxdocs/Person/JoshuaWatt-0ef7e15a-5628-4bd9-8485-a3eace6dcc4f", - "creationInfo": "_:creationinfo", - "name": "Joshua Watt", - "externalIdentifier": [ - { - "type": "ExternalIdentifier", - "externalIdentifierType": "email", - "identifier": "JPEWhacker@gmail.com" - } - ] - }, - { - "type": "CreationInfo", - "@id": "_:creationinfo", - "specVersion": "3.0.0", - "createdBy": [ - "https://spdx.org/spdxdocs/Person/JoshuaWatt-0ef7e15a-5628-4bd9-8485-a3eace6dcc4f" - ], - "created": "2024-03-06T00:00:00Z" - }, - { - "type": "SpdxDocument", - "spdxId": "https://spdx.org/spdxdocs/Document1-7bd25aaf-64b7-4ccc-aa85-84695cef4c17", - "creationInfo": "_:creationinfo", - "profileConformance": [ - "core" - ], - "rootElement": [ - "https://spdx.org/spdxdocs/Person/JoshuaWatt-0ef7e15a-5628-4bd9-8485-a3eace6dcc4f" - ] - } - ] -} -``` - -Now, in our new document we can reference the "Joshua Watt" person by simply -referring to it by its spdxId. For example, to indicate that this new document -was also written by the same person, we can reference it in the creation info -(note the [createdBy][Property_createdBy] property): - -```json ---- -{ - "@context": "https://spdx.org/rdf/3.0.0/spdx-context.jsonld", - "@graph": [ - { - "type": "CreationInfo", - "@id": "_:creationinfo1", - "specVersion": "3.0.0", - "createdBy": [ - "https://spdx.org/spdxdocs/Person/JoshuaWatt-0ef7e15a-5628-4bd9-8485-a3eace6dcc4f" - ], - "created": "2024-05-08T00:00:00Z" - }, -``` - -## Imports - -This is sufficient to link documents in JSON-LD, but it is missing some useful -information that SPDX requires you to specify. Namely, since spdxIds are _not_ -necessarily resolvable URLs, this gives no indication as to where the -[Person][Class_Person] can be found. In order to provide this information, SPDX -requires that all externally referenced spdxIds be enumerated in the -[imports][Property_imports] property of the local -[SpdxDocument][Class_SpdxDocument]. Lets start by writing the preamble for the -SpdxDocument: - -```json - { - "type": "SpdxDocument", - "spdxId": "https://spdx.org/spdxdocs/Document2-72d52ac3-3642-47be-9f83-8fbef6a962b4", - "creationInfo": "_:creationinfo1", - "profileConformance": [ - "core", - "software" - ], - "imports": [ -``` - -The [imports][Property_imports] property is a list of -[ExternalMap][Class_ExternalMap] objects, one for each external spdxId being -referenced. The class has one required property called -[externalSpdxId][Property_externalSpdxId] which is the external spdxId being -described: - -```json - { - "type": "ExternalMap", - "externalSpdxId": "https://spdx.org/spdxdocs/Person/JoshuaWatt-0ef7e15a-5628-4bd9-8485-a3eace6dcc4f", - -``` - -In addition to this, there are a few optional fields. The first is the -[locationHint][Property_locationHint] property which is a URI that indicates -where the document that contains the external spdxId may be located. Since this -is an actual resolvable URI, consumers of the document can use locate the -unresolved spdxId. While optional, this field is recommended: - -```json - "locationHint": "http://downloads.example.com/Document1.spdx.json", -``` - -In addition to the location, the [verifiedUsing][Property_verifiedUsing] -property indicates how a user can verify the integrity of the external document -to ensure it has not been tampered with. It can be 0 or more -[IntegrityMethod][Class_IntegrityMethod] objects. While also optional, it is -recommended to include at least one: - -```json - "verifiedUsing": [{ - "type": "Hash", - "algorithm": "sha256", - "hashValue": "3ba8c249c1ba1b6fe20582de88a5123b317632a5a94ba27199d01724df4eb149" - }], -``` - -Finally, the [definingArtifact][Property_definingArtifact] allows a much richer -expression of information about the document that contains the external spdxId -by linking to a complete [Artifact][Class_Artifact] element. This field is also -optional, but if you need the impressive expressive power of the `Artifact` -class, it is also recommended: - -```json - "definingArtifact": "https://spdx.org/spdxdocs/Artifact-4762f4c5-3362-47e9-9595-5182235ef577" -``` - -It should be noted that it is reasonable for the `definingArtifact` itself to -be an external spdxId, as long as it also has the relevant entry in `imports`. - -We also need to add an import for the [SpdxDocument][Class_SpdxDocument] that -contains the author, as we will be referencing it later, so lets do that now: - -```json - }, - { - "type": "ExternalMap", - "externalSpdxId": "https://spdx.org/spdxdocs/Document1-7bd25aaf-64b7-4ccc-aa85-84695cef4c17", - "locationHint": "http://downloads.example.com/Document1.spdx.json", - "verifiedUsing": [{ - "type": "Hash", - "algorithm": "sha256", - "hashValue": "3ba8c249c1ba1b6fe20582de88a5123b317632a5a94ba27199d01724df4eb149" - }], - "definingArtifact": "https://spdx.org/spdxdocs/Artifact-4762f4c5-3362-47e9-9595-5182235ef577" - } -``` - -And that is it! By providing this information you are explaining to consumer of -the document how they can resolve the external spdxIds. - -Lets close out our SpdxDocument - -```json - ] - }, -``` - -Since we are using an [Artifact][Class_Artifact] that describes the SpdxDocument -containing the external spdxId, we need to write that now: - -```json - { - "type": "software_File", - "spdxId": "https://spdx.org/spdxdocs/Artifact-4762f4c5-3362-47e9-9595-5182235ef577", - "creationInfo": "_:creationinfo1", - "software_fileKind": "file", - "software_primaryPurpose": "file", - "software_contentType": "application/spdx+json", - "verifiedUsing": [{ - "type": "Hash", - "algorithm": "sha256", - "hashValue": "3ba8c249c1ba1b6fe20582de88a5123b317632a5a94ba27199d01724df4eb149" - }], - "originatedBy": [ - "https://spdx.org/spdxdocs/Person/JoshuaWatt-0ef7e15a-5628-4bd9-8485-a3eace6dcc4f" - ], - "suppliedBy": "https://spdx.org/spdxdocs/Person/JoshuaWatt-0ef7e15a-5628-4bd9-8485-a3eace6dcc4f", - "releaseTime": "2024-03-06T00:00:00Z", - "builtTime": "2024-03-06T00:00:00Z" - }, -``` - -Finally, since we are using an [Artifact][Class_Artifact], we need to add a -[Relationship][Class_Relationship] with type `serailizedInArtifact` to link the -artifact and the serialized [SpdxDocument][Class_SpdxDocument]. Note that this -is where the `spdxId` of the `SpdxDocument` is referenced which is why we -needed to import it earlier: - -```json - { - "spdxId": "https://spdx.org/spdxdocs/Relationship/serializedInArtifact-141ec767-40f2-4aad-9658-ac2703f3a7d9", - "type": "Relationship", - "creationInfo": "_:creationinfo1", - "relationshipType": "serializedInArtifact", - "from": "https://spdx.org/spdxdocs/Document1-7bd25aaf-64b7-4ccc-aa85-84695cef4c17", - "to": [ - "https://spdx.org/spdxdocs/Artifact-4762f4c5-3362-47e9-9595-5182235ef577" - ] - } - ] -} -``` - -Happy Linking! - -[Class_Artifact]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Artifact -[Class_Element]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element -[Class_ExternalMap]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/ExternalMap -[Class_IntegrityMethod]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/IntegrityMethod -[Class_Person]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Person -[Class_SpdxDocument]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/SpdxDocument -[Class_Relationship]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Relationship -[JSON_LD]: https://json-ld.org/ -[Property_createdBy]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/createdBy -[Property_definingArtifact]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/definingArtifact -[Property_externalSpdxId]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/externalSpdxId -[Property_imports]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/imports -[Property_verifiedUsing]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/verifiedUsing -[Property_locationHint]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/locationHint diff --git a/docs/annexes/diffs-from-previous-editions.md b/docs/annexes/diffs-from-previous-editions.md deleted file mode 100644 index 8fc1f2b468..0000000000 --- a/docs/annexes/diffs-from-previous-editions.md +++ /dev/null @@ -1,941 +0,0 @@ -# Annex A: Differences from previous editions (Informative) - -## A.1 Differences between V3.0 and V2.3 - -### SPDX meaning - -In previous editions of the specification, SPDX meant "Software Package Data Exchange". - -Starting with V3.0, the scope of SPDX has expanded beyond software and now means "System Package Data Exchange". - -### Structural Differences - -These are the most significant breaking changes requiring a change in logic to handle a different model or structure for the information. Each structural difference will describe the change, describe an approach to translate from 2.3 to 3.0, and provide a rationale for the change. - -#### External Document Reference - -##### Description of Change - -The purpose of the SPDX 2.3 structure “ExternalDocumentRef” is now covered by two separate structures: - -- NamespaceMap which maps short identifiers used in serializations to full namespace URI’s to support terseness in serialization of element identifiers -- ExternalMap which maps an element identifier for an element defined externally to verification and location information - -The externalDocumentRef property on the SpdxDocument has been replaced by import property and namespace property. - -Another change is the SPDX document checksum field has been replaced with a “verifiedUsing” property on the ElementCollection. The “verifiedUsing” which has 0 or more “IntegrityMethod” which should be the checksum of the SPDX document. - -##### Translating from 2.3 to 3.0 - -Each ExternalDocumentRef instance will translate as follows: - -- An entry would be created in the Namespace map for the external document namespace - - The value of the DocumentRef-[idstring] would be used for the prefix property in the NamespaceMap. - - The value of the documentNamespace appended with a “#” would be used for the namespace in the NamespaceMap. -- An entry would be created in the ExternalMap for the external document ref - - A string identifier consisting of the DocumentRef-[idstring] (the same value as the prefix in the NamespaceMap) concatenated with a “:” and then concatenated with “SPDXRef-DOCUMENT” would be used for the externalSpdxId in the ExternalMap. - - An integrity method of “Hash” will be created with the same information as the checksum property and will be referenced using the “verifiedUsing” property on the ExternalMap entry. -- An entry would be created in the ExternalMap for each element referenced in the current SpdxDocument that is originally specified in the referenced SpdxDocument. - - A string identifier consisting of the DocumentRef-[idstring] (the same value as the prefix in the NamespaceMap) concatenated with a “:” and then concatenated with the local portion of the element identifier would be used for the externalSpdxId in the ExternalMap - - A “definingDocument” property would be specified containing a string identifier consisting of the DocumentRef-[idstring] concatenated with a “:” and then concatenated with “SPDXRef-DOCUMENT”. This is a shortcut linkage to tie the referenced element to its defining SpdxDocument for verification and location information. - -##### Rationale - -A key difference between SPDX 2.3 and SPDX 3.0 is that in SPDX 2.3 elements are always expressed within or referenced in relation to a single enclosing SpdxDocument while in SPDX 3.0 a key design principle is that all elements may be expressed and referenced independent of any other element including SpdxDocument. This independence is required to support a variety of content exchange and analysis use cases. - -For example, in SPDX 2.3 if you wish to express even a single package you specify it within an SpdxDocument and its identifier namespace is restricted to the namespace of the SpdxDocument. In SPDX 3.0 you could specify a single package within an SpdxDocument element (or any other subclass of ElementCollection such as Bundle, Bom, Sbom, etc.) but you could also simply specify it on its own without any enclosing collection element. In addition, in SPDX 3.0 the identifier of the package may share a namespace with an enclosing collection element such as SpdxDocument if desired but it is equally valid for it to have any namespace desired unconstrained by any other element namespace whether it is expressed within a collection element such as SpdxDocument or not. - -In this example, in SPDX 2.3 if you referenced the package within the same SpdxDocument that it is defined in you would utilize the local portion of its identifier and presume that the namespace is the same as the SpdxDocument namespace. If you referenced it from an SpdxDocument other than the one it is defined in you would use an ExternalDocumentRef to specify a prefix name for the other SpdxDocument to be used within the current SpdxDocument, the URI namespace/identifier for the other SpdxDocument, and a checksum for the other SpdxDocument. To reference the package you would then use an identifier combining the external document ref prefix and the local portion of the identifier. - -The ExternalDocumentRef structure in SPDX 2.3 is based on the presumptions that elements are always defined within SpdxDocuments, that external elements can always be referenced via a containing SpdxDocument and that element identifiers have a namespace from their original containing SpdxDocument. None of these three presumptions hold true for SPDX 3.0 so a slightly modified structure is necessary to support the two use cases previously covered by ExternalDocumentRef in SPDX 2.3: 1) the ability to specify identifier namespace prefixes and accompanying namespaces for SPDX elements to support more terse serialized expression of content with integrity across serialization forms, 2) the ability to specify which elements in the current subclass of ElementCollection (e.g., SpdxDocument) are only referenced from that collection and defined elsewhere, along with details regarding their verification and location. - -The Namespace map structure in SPDX 3.0 fully supports the namespace prefixing use case for SpdxDocuments previously covered by ExternalDocumentRef but also equally covers the same use case capability for all element types and for any number of element identifier namespaces (in SPDX 3.0 all elements within an SpdxDocument are not required to have the same namespace and can actually be any desired mix of namespaces) to support this capability required in SPDX 3.0. - -The ExternalMap structure in SPDX 3.0 fully supports the external element (including SpdxDocument elements) referencing use case for SpdxDocuments previously covered by ExternalDocumentRef but also equally covers the same use case capability for any elements whether they were originally defined within an SpdxDocument or not to support this capability required in SPDX 3.0. The ExternalMap structure in SPDX 3.0 provides the ability to specify verification and location details for any element, not just SpdxDocuments, if appropriate but also provides simple linkage, using the “definingDocument'' property, from element entries in the ExternalMap to SpdxDocument entries in the ExternalMap where the elements were defined within the SpdxDocument and verification of the elements can be achieved via proxy to the SpdxDocument “verifiedUsing” information (this is how the SPDX 2.3 ExternalDocumentRef structure currently works). - -#### Agent - -##### Description of Change - -The creator property in SPDX 2.3 has been replaced by createdBy and createdUsing properties with a type Agent and Tool resp. The supplier property has been replaced by a property suppliedBy with a type Agent. Additional suppliers can be provided with a a relationship to an availableFrom relationship. The originator property type has been replaced with the originatedBy property with a type Agent. - -An Agent can be a Person, Organization, or Software Agent. It can also just be an Agent if it is not known what specific type an Agent is. - -##### Translating from 2.3 to 3.0 - -The SPDX 2.3 creator string would be parsed and the appropriate Person, Organization or Tool would be created depending on if the prefix is “Person: ”, “Organization:” or “Tool: ” resp. The required createdBy field for Agent or Tool may point to itself if no other information is available. The createdUsing property would be used for Tool whereas the createdBy property would be used for Person and Organization. The name would map to the “name” property. If an email address is present, it would translate to an external identifier. - -Note that in 3.0 the createdBy is a required field. There will be situations where only a Tool is provided. In that case, createdBy should point to a SoftwareAgent should be created using the same information as the Tool. - -##### Rationale - -The 3.0 format is more machine readable and structured (e.g. you do not need to parse the type from the string value). It is also more flexible in that an Agent can be used even if it is not known what the Agent type is. - -#### File Contributor - -##### Description of Change - -The fileContributor property on File has been replaced by the originatedBy property on Artifact. - -##### Translating from 2.3 to 3.0 - -For each fileContributor string in SPDX 2.3, an Person should be created and added to the originatedBy list for the File artifact. - -##### Rationale - -The Artifact property originatedBy should be used to describe file contributor information in place of the fileContributor property. - -#### File Type - -##### Description of Change - -The FileType enumeration has been replaced by two fields, the [media type](https://www.iana.org/assignments/media-types/media-types.xhtml) string as maintained by IANA for the content of the file and an enumeration of SoftwarePurpose for the purpose of the file. - -The property name fileType has been replaced by a property name contentType. - -##### Translating from 2.3 to 3.0 - -##### Rationale - -One of the things that we identified is that `FileType` was being used for two things: - -1. Describing the purpose of the file. -2. Describing the type of content in the file. - -For SPDX 3.0 we split this into two properties: - -- `SoftwarePurpose` to capture the purpose (which is of type `SoftwarePurpose`). -- `ContentType` to capture the type of content (which is of type `MediaType`). - -The name `ContentType` was chosen to mirror the Content-Type header in HTTP (which is also of type MediaType) and to express that this is describing the type of content (as opposed to metadata, headers, or something else). For example, if (and not saying we would) we extended `File` in the future to be able to capture the type of executable header a file has (e.g. ELF), that could also be of type `MediaType` but the property name might be `ExecutableHeaderType`. - -An example conversion table from SPDX 2.3 `FileType` to SPDX 3.0 `ContentType` or `SoftwarePurpose` can look like this: - -| SPDX 2 File Type | SPDX 3 Software Purpose | SPDX 3 Content Type | -|------------------|-------------------------|---------------------| -| ARCHIVE | Archive | | -| BINARY | | application/octet-stream | -| SOURCE | Source | | -| TEXT | | text/plain | -| APPLICATION | Application | | -| AUDIO | | audio/* | -| IMAGE | | image/* | -| VIDEO | | video/* | -| DOCUMENTATION | Documentation | | -| SPDX | | text/spdx | -| OTHER | Other | | - -#### Package File Name - -##### Description of Change - -The packageFileName property and packageChecksum property has been replaced by a relationship from a Package to a File. A relationship type of hasDistributionArtifact should be used. - -##### Translating from 2.3 to 3.0 - -Create an SPDX File with the name from the packageFileName and a verifiedUsing value from the packageChecksum for a single file. If the packageFileName is a directory, then the SPDX File is created with the directory name and is verified using the contentIdentifier property on the File and a fileKind of directory. Create a hasDistributionArifact relationship from the SPDX Package to the SPDX File. - -##### Rationale - -Providing a File relationship to the download location will include more detailed and complete information about the package file name used. - -#### External Identifiers - -##### Description of Change - -In SPDX 3.0, a properties externalIdentifier and contentIdentifier with types ExternalIdentifier and ContentIdentifier were introduced. This is in addition to retaining the ExternalRef property and classes. - -In SPDX 2.3, both identifiers and references were captured in the externalRef property for packages. - -In addition to the structural changes, the “url” ExternalRef type was removed and is replaced by the “securityOther” ExternalRef type. - -##### Translating from 2.3 to 3.0 - -The following ExternalRef Types should be converted to ExternalIdentifiers: - -- cpe22Type -- cpe23Type -- swid -- purl - -The following ExternalRef Types should be converted to ContentIdentifers: - -- gitoid -- swh - -All other ExternalRef types should remain as ExternalRef’s. - -The url ExternalRef type should be converted to a “securityOther”. - -##### Rationale - -Distinguishing identifiers from references is key to several integrity and provenance use cases. Creating a separate property and type enables easier identification of identifiers. - -#### Package URL - -##### Description of Change - -In SPDX 3.0, Package URL is a new property for Artifact which is a superclass of Package. - -Package URL is an External Ref type in SPDX 2.3. - -##### Translating from 2.3 to 3.0 - -If there is a single ExternalReference of type purl without the optional ExternalRef comment property, place that in the packageUrl property. - -##### Rationale - -Package URL is a very common method of identifying software packages. Moving this to a property makes it significantly simpler to find and correlate Package URL identifiers. - -#### Annotation - -##### Description of Change - -Annotations are now subclasses of Element, so it inherits a number of new optional properties including names, annotations, and its own relationships. - -Annotations are no longer a property of an Element. It is now a standalone element with a “subject” field which points to the Element being annotated. - -##### Translating from 2.3 to 3.0 - -A new Annotation element would be created for every annotation property in an element (Package, File or Snippet). The subject property would point to the Element which has the Annotation as a property. - -The annotator from SPDX 2.3 should be translated to one of the creators for the creationInfo for the Annotation and the annotationDate should be translated to the created field in the same creationInfo. The creationInfo for the Annotation should be the creationInfo of the SPDX 2.3 document. - -The SPDX 2.3 “comment” should use the statement field in SPDX 3.0. - -##### Rationale - -Changing from a property to a standalone element allows for relationships to exist outside the element itself (e.g. you can now create an amended SPDX document which has a new annotation for an element defined in the original document). This also supports third parties' ability to assert Annotations on Elements that they did not create. - -#### Relationship - -##### Description of Change - -The structure of the Relationship class has changed to have a single direction and allow more than one related SPDX Elements. Relationships are now subclasses of Element, so it inherits a number of new optional properties including names, annotations, and its own relationships. - -Relationships are no longer a property of an Element. It is now a standalone element with a “from” and “to” field. - -A new property “completeness' ' complements the use of NONE and NOASSERTION for the related SPDX elements. - -##### Translating from 2.3 to 3.0 - -The “from” property would be populated by the SPDX Element which has the relationship property. The “to” property will be the relatedSpdxElement. - -When translating the relationshipType, the “from” and “to” may need to be swapped - the table below will have a “Y” in the “Swap to and from?” column when this is necessary. - -The completeness property would be constructed based on the following: - -- “to” value is NONE: complete -- “to” value is NOASSERTION: noAssertion -- “to” value is an SPDX element: No value for the completeness - uses the default - -The following table reflects the translation for relationship types from SPDX 2.3 to SPDX 3.0: - -| SPDX 2.3 Relationship Type | SPDX 3.0 Relationship Type | Swap to and from? | LifecycleScopeType | -|----------------------------|----------------------------|-------------------|--------------------| -| AMENDS | amendedBy | Y | | -| ANCESTOR_OF | ancestorOf | | | -| BUILD_DEPENDENCY_OF | dependsOn | Y | build | -| BUILD_TOOL_OF | usesTool | Y | build | -| CONTAINED_BY | contains | Y | | -| CONTAINS | contains | | | -| COPY_OF | copiedTo | Y | | -| DATA_FILE_OF | hasDataFile | Y | | -| DEPENDENCY_MANIFEST_OF | hasDependencyManifest | Y | | -| DEPENDENCY_OF | dependsOn | Y | various lifecycle scope | -| DEPENDS_ON | dependsOn | | various lifecycle scope | -| DESCENDANT_OF | descendantOf | | | -| DESCRIBED_BY | describes | Y | | -| DESCRIBES | describes | | | -| DEV_DEPENDENCY_OF | dependsOn | Y | development | -| DEV_TOOL_OF | usesTool | Y | development | -| DISTRIBUTION_ARTIFACT | hasDistributionArtifact | | | -| DOCUMENTATION_OF | hasDocumentation | Y | | -| DYNAMIC_LINK | hasDynamicLink | Y | build, runtime | -| EXAMPLE_OF | hasExample | Y | | -| EXPANDED_FROM_ARCHIVE | expandsTo | Y | | -| FILE_ADDED | hasAddedFile | Y | | -| FILE_DELETED | hasDeletedFile | Y | | -| FILE_MODIFIED | modifiedBy | | | -| GENERATED_FROM | generates | Y | | -| GENERATES | generates | | | -| HAS_PREREQUISITE | hasPrerequisite | | various lifecycle scope | -| METAFILE_OF | hasMetadata | Y | | -| OPTIONAL_COMPONENT_OF | hasOptionalComponent | Y | | -| OPTIONAL_DEPENDENCY_OF | hasOptionalDependency | Y | various lifecycle scope | -| OTHER | other | | | -| PACKAGE_OF | packagedBy | Y | | -| PATCH_FOR | patchedBy | Y | | -| PATCH_APPLIED | patchedBy | Y | | -| PREREQUISITE_FOR | hasPrerequisite | Y | various lifecycle scope | -| PROVIDED_DEPENDENCY_OF | hasProvidedDependency | Y | various lifecycle scope | -| REQUIREMENT_DESCRIPTION_FOR | hasRequirement | Y | various lifecycle scope | -| RUNTIME_DEPENDENCY_OF | dependsOn | Y | runtime | -| SPECIFICATION_FOR | hasSpecification | Y | various lifecycle scope | -| STATIC_LINK | hasStaticLink | | various lifecycle scope | -| TEST_CASE_OF | hasTestCase | Y | | -| TEST_DEPENDENCY_OF | dependsOn | Y | test | -| TEST_OF | hasTest | Y | various lifecycle scope | -| TEST_TOOL_OF | usesTool | Y | test | -| VARIANT_OF | hasVariant | Y | | - -##### Rationale - -The addition of the completeness attribute is clearer than the use of NONE and NOASSERTION. - -Changing from a property to a standalone element allows for relationships to exist outside the element itself (e.g. you can now create an amended SPDX document which has a new relationship for an element defined in the original document). This enables primary Element creating parties as well as third parties to express significantly greater contextual detail among content they create as well as content created by others. - -#### Snippet - -##### Description of Change - -Byte and line range types have been changed from a StartEndPointer type to a PositiveIntegerRange. Byte range is now optional. - -##### Translating from 2.3 to 3.0 - -Iterate through the “ranges” property. Any startPointer and endPointer with a property of “offset” would be translated to a snippetByteRange property. Any startPointer and endPointer with a property of “lineNumber” would translate to a snippetLineRange property. - -A new Relationship would be created with the “from” pointing to the snippetFromFile and the “to” pointing to the Snippet. They relationshipType would be CONTAINS. - -##### Rationale - -Using the W3C Pointer standard introduced significant complexity in the SPDX 2.X specification. Although there may be some benefit in using a published standard, we have not found any instances where the W3C Pointer ontology was useful for SPDX use cases. - -Changing the snippetFromFile from a property to a relationship [to be filled in]. - -#### SpecVersion - -##### Description of Change - -The type of SpecVersion is changed from a simple string without constraints to a SemVer string which must follow the [Semantic Versioning format](https://semver.org/). - -This adds a constraint where a patch version is required. Previous usage of the SpecVersiononly included the major and minor version. - -##### Translating from 2.3 to 3.0 - -Add a patch version of “0” to any previous spec version. - -##### Rationale - -#### The additional constraints align with best practices for versioning strings - -#### LicenseListVersion - -##### Description of Change - -The type of LicenseListVersion is changed from a simple string without constraints to a SemVer string which must follow the [Semantic Versioning format](https://semver.org/). - -This adds a constraint where a patch version is required. Previous usage of the SPDX license list only included the major and minor version. - -##### Translating from 2.3 to 3.0 - -Add a patch version of “0” to any previous license list version. - -##### Rationale - -The additional constraints align with best practices for versioning strings. - -### Properties Removed - -Below is a list of properties present in 2.3 and not present in 3.0. The Range / Where used is where the property was used in the SPDX 2.3 model. - -#### example - -##### SPDX 2.3 Model Name - -example - -##### Tag/Value Name - -Not used - -##### Range / Where Used - -LicenseException - -##### Rationale - -This field has not been used. - -#### LicenseInfoInFiles - -##### SPDX 2.3 Model Name - -licenseInfoInFiles - -##### Tag/Value Name - -LicenseInfoInFiles - -##### Range / Where Used - -Package - -##### Rationale - -This field is redundant with the declaredLicense property in the Files contained in the Package. It is recommended that the licenseInfoInFiles can be added as an Annotation to the Package in the format: “SPDX 2.X LicenseInfoInFiles: [expression1], [expression2]” where the [expressions] are the string representation of the license expressions. - -#### FilesAnalyzed - -##### SPDX 2.3 Model Name - -filesAnalyzed - -##### Tag/Value Name - -FilesAnalyzed - -##### Range / Where Used - -Package - -##### Rationale - -Many users of the SPDX 2.X spec reported this property as very confusing. - -NOTE: There is no longer a way to specific checksums are required for files. This is being tracked in [Issue #84](https://github.com/spdx/spdx-3-model/issues/84). - -### Naming Differences - -Below is a list of properties and classes where the name has been changed from 2.3 to 3.0. The Range / Where used is where the property was used in the SPDX 2.3 model. - -#### Release Date - -##### SPDX 2.3 Model Name - -releaseDate - -##### Tag/Value Name - -ReleaseDate - -##### New Name - -releaseTime - -##### Range / Where Used - -Package - -##### Rationale - -Better reflects the granularity of the field. - -#### Build Date - -##### SPDX 2.3 Model Name - -buildDate - -##### Tag/Value Name - -BuildDate - -##### New Name - -buildTime - -##### Range / Where Used - -Package - -##### Rationale - -Better reflects the granularity of the field. - -#### Valid Until Date - -##### SPDX 2.3 Model Name - -validUntilDate - -##### Tag/Value Name - -ValidUntilDate - -##### New Name - -validUntilTime - -##### Range / Where Used - -Package - -##### Rationale - -Better reflects the granularity of the field. - -#### External Document Reference - -##### SPDX 2.3 Model Name - -externalDocumentRef - -##### Tag/Value Name - -ExternalDocumentRef - -##### New Name - -import - -##### Range / Where Used - -SpdxDocument (Creation Information) - -##### Rationale - -Feedback from SPDX 2.X usage is that externalDocumentRef is confusing due to the similar externalRef property. - -NOTE: See structural changes related to this property - -#### Checksum Class / Data Type - -##### SPDX 2.3 Model Name - -Checksum class name and checksum property name - -##### Tag/Value Name - -FileChecksum, PackageChecksum - -##### New Name - -verifiedUsing property and Hash class - -##### Range / Where Used - -Package, File - -##### Rationale - -More general concept allowing for different verification algorithms for different scenarios. - -#### Checksum Algorithm - -##### SPDX 2.3 Model Name - -checksumAlgorithm - -##### Tag/Value Name - -N/A - parsed from a string following the Checksum: keyword. - -##### New Name - -hashAlgorithm - -##### Range / Where Used - -Package, File - -##### Rationale - -The term “hash” better represents the intent of this property which is to validate the integrity of the data whereas the term “checksum” is typically for the purpose of error checking. - -#### Name - -##### SPDX 2.3 Model Name - -packageName, fileName - -##### Tag/Value Name - -PackageName, FileName - -##### New Name - -name - -##### Range / Where Used - -Package, File - -##### Rationale - -In the SPDX 2.3 RDF Ontology, both spdx:fileName and spdx:packageName are sub-properties of spdx:name. The OWL has a restriction that spdx:File has exactly one spdx:fileName and spdx:Package has exactly one spdx:packageName. - -Changing these restrictions to just spdx:name would simplify the model. - -#### Version - -##### SPDX 2.3 Model Name - -versionInfo - -##### Tag/Value Name - -PackageVersion - -##### New Name - -packageVersion - -##### Range / Where Used - -Package - -##### Rationale - -This change would make the Tag/Value and RDF values consistent. - -#### Home Page - -##### SPDX 2.3 Model Name - -doap:homepage - -##### Tag/Value Name - -PackageHomePage - -##### New Name - -homePage - -##### Range / Where Used - -##### Rationale - -Uses a consistent namespace for SPDX properties. - -#### Annotation Comment - -##### SPDX 2.3 Model Name - -rdfs:comment - -##### Tag/Value Name - -AnnotationComment - -##### New Name - -statement - -##### Range / Where Used - -Element (Package, File, Snippet) - -##### Rationale - -The rdfs:comment property is optional and has slightly different semantics in other uses (e.g. comments on Elements). Changing the property name clearly distinguishes this usage as a mandatory property for an Annotation. - -#### With Exception Operator - -##### SPDX 2.3 Model Name - -WithExceptionOperator - -member property in WithExceptionOperator - -licenseException property in WithExceptionOperator - -##### Tag/Value Name - -With (part of License Expression) - -##### New Name - -WithAdditionOperator - -subjectLicense - -subjectAddition - -##### Range / Where Used - -Package, File, Snippet - -##### Rationale - -Custom Additions have been added in SPDX 3.0 which operate in a similar manner to listed License Exceptions. The new type and property names are more general to accommodate both custom additions and listed license Exceptions. - -#### License Exception - -##### SPDX 2.3 Model Name - -LicenseException - -licenseExceptionId property in LicenseException - -licenseExceptionText property in LicenseException - -name property in LicenseException - -##### Tag/Value Name - -Not used in Tag/Value - -##### New Name - -ListedLicenseException - -additionId - -additionText - -additionName - -##### Range / Where Used - -Package, File, Snippet - -##### Rationale - -Custom Additions have been added in SPDX 3.0 which operate in a similar manner to listed License Exceptions. The new type and property names are more general to accommodate both custom additions and listed license Exceptions. - -#### ExtractedLicenseInfo - -##### SPDX 2.3 Model Name - -ExtractedLicenseInfo - -##### Tag/Value Name - -ExtractedText - -##### New Name - -CustomLicense - -##### Range / Where Used - -Package, File, Snippet, Document - -##### Rationale - -The SPDX 2.X term implied that the only property was text when in fact there are several properties in common with the listed licenses. See [model issue #233](https://github.com/spdx/spdx-3-model/issues/223) for context. - -#### licenseName - -##### SPDX 2.3 Model Name - -licenseName - -##### Tag/Value Name - -LicenseName - -##### New Name - -name - -##### Range / Where Used - -License, ListedLicense, ExtractedText - -##### Rationale - -“name” is used in the Element class. Since License is a type of (subclass of) Element, it should use the same field otherwise there would be redundant fields for the same purpose. - -#### LicenseComment - -##### SPDX 2.3 Model Name - -licenseComment - -##### Tag/Value Name - -LicenseComment - -##### New Name - -comment - -##### Range / Where Used - -License, ListedLicense - -##### Rationale - -“comment” is used in the Element class. Since License is a type of (subclass of) Element, it should use the same field otherwise there would be redundant fields for the same purpose. - -#### LicenseID - -##### SPDX 2.3 Model Name - -licenseId - -##### Tag/Value Name - -LicenseId - -##### New Name - -spdxId - -##### Range / Where Used - -License, ListedLicense - -##### Rationale - -“spdxId” is used in the Element class. Since License is a type of (subclass of) Element, it should use the same field otherwise there would be redundant fields for the same purpose. - -##### Range / Where Used - -License, ListedLicense - -##### Rationale - -#### Primary Package Purpose - -##### SPDX 2.3 Model Name - -primaryPackagePurpose - -##### Tag/Value Name - -PrimaryPackagePurpose - -##### New Name - -primaryPurpose - -##### Range / Where Used - -Package - -##### Rationale - -The purpose property is now available for files and snippets in addition to Package resulting in a more general name of primaryPurpose. - -Note that additional purposes can be added using the additionalPurpose property. - -### Serialization Formats - -SPDX 3.0 implements a JSON-LD format which has consistent class and property names with the model. - -See the SPDX 3.0 JSON Schema for the format specifics. - -The Tag/Value, YAML, RDF/XML and Spreadsheet formats are not supported. - -Additional serialization formats are being considered for the SPDX 3.1 release. - -## A.2 Differences between V2.3 and V2.2.2 - -V2.3 has added new fields to improve the ability to capture security related information and to improve interoperability with other SBOM formats. - -Key changes include: - -- Added fields to Clause 7 ( Package Information ) to describe "Primary Package Purpose" and standardize recording of "Built Date", "Release Date", "Valid Until Date". - -- Added hash algorithms (SHA3-256, SHA3-384, SHA3-512, BLAKE2b-256, BLAKE2b-384, BLAKE2b-512, BLAKE3, ADLER32 ) to the set recognized by 7.10 (Package Checksum field) and 8.4 (File checksum field) - -- Update Clause 7, 8, and 9 to make several of the licensing properties optional rather than requiring the use of "NOASSERTION" when no value is provided. - -- Update Clause 11 to add the new relationship types: REQUIREMENT_DESCRIPTION_FOR and SPECIFICATION_FOR. - -- Update Annex B ( License matching guidelines and templates ) to use the License List XML format - -- Update Annex F ( External Repository Identifiers ) to expand security references to include advisory, fix, URL, SWID. Expand persistent identifiers to include gitoid. - -- Update Annex G ( SPDX Lite Profile ) to include NTIA SBOM mandatory minimum fields as required. - -- Update Annex H to documented how the snippet information in files to be consistent with REUSE recommendations. - -- Added Annex K ( How To Use SPDX in Different Scenarios ) to illustrate linking to external security information, and illustrate how the NTIA SBOM mandatory minimum elements map to SPDX fields. - -## A.3 Differences between V2.2.2 and V2.2.1 - -V2.2.2 fixed formatting, grammatical and spelling issues found since ISO/IEC 5962:2021 SPDX v2.2.1 was published. No new fields were added. - -Key changes include: - -- Clarify Optional Cardinality contradictions - -- Update OWL document - -- Update JSON schema to fix typos and add missing required fields. - -- Clarify Information on using License List short form identifiers. - -- It fixed annex lettering inconsistencies. It also moved CC-BY-3.0 to the end of the spec to keep annex letters more consistent in future versions. Here is the translation between lettering in V2.2.2 and the version that came before it: - -**Table A.1 — SPDX V2.2.2 Organizational Changes** - -| Title | V2.2.1 ([spdx.dev](https://spdx.dev/)) | V2.2.1 (ISO) | V2.2.2 | -| ----- | -------------------------------------- | ------------ | ------ | -| SPDX Lite | Annex H/G* | Annex G | Annex G | -| SPDX File Tags | Annex I/H* | Annex H | Annex H | -| Differences from Earlier SPDX Versions | Annex J/I* | Annex I | Annex I | -| Creative Commons Attribution License 3.0 Unported | Annex G | [omitted] | Annex J [omitted in ISO version] | - -*_This edition featured inconsistent lettering._ - -## A.4 Differences between V2.2.1 and V2.2 - -There were no technical differences; V2.2.1 is V2.2 reformatted for submission to ISO via the PAS process. As a result, new clauses were added causing the previous clause-numbering sequence to change. Also, Annexes went from having Roman numbers to Latin letters. Here is the translation between numbering in V2.2.1 and the version that came before it: - -**Table A.2 — SPDX V2.2.1 Organizational Changes** - -| Title | V2.2 | V2.2.1 ([spdx.dev](https://spdx.dev/)) | V2.2.1 (ISO) | -| ----- | --------- | -------------------------------------- | ------------ | -| Scope | N/A | Clause 1 | Clause 1 | -| Normative references | N/A | Clause 2 | Clause 2 | -| Terms and definitions | N/A | Clause 3 | Clause 3 | -| Conformance | N/A | Clause 4 | Clause 4 | -| Composition of an SPDX document | N/A | Clause 5 | Clause 5 | -| Document Creation Information | Chapter 2 | Clause 6 | Clause 6 | -| Package Information | Chapter 3 | Clause 7 | Clause 7 | -| File Information | Chapter 4 | Clause 8 | Clause 8 | -| Snippet Information | Chapter 5 | Clause 9 | Clause 9 | -| Other Licensing Information Detected | Chapter 6 | Clause 10 | Clause 1 | -| Relationship between SPDX Elements Information | Chapter 7 | Clause 11 | Clause 1 | -| Annotation Information | Chapter 8 | Clause 12 | Clause 1 | -| Review Information (deprecated) | Chapter 9 | Clause 13 | Clause 1 | -| SPDX License List | Appendix I | Annex A | Annex A | -| License Matching Guidelines and Templates | Appendix II | Annex B | Annex B | -| RDF Object Model and Identifier Syntax | Appendix III | Annex C | Annex C | -| SPDX License Expressions | Appendix IV | Annex D | Annex D | -| Using SPDX short identifiers in Source Files | Appendix V | Annex E | Annex E | -| External Repository Identifiers | Appendix VI | Annex F | Annex F | -| Creative Commons Attribution License 3.0 Unported | Appendix VII | Annex G | [omitted] | -| SPDX Lite | Appendix VIII | Annex H/G* | Annex G | -| SPDX File Tags | Appendix IX | Annex I/H* | Annex H | -| Differences from Earlier SPDX Versions | N/A | Annex J/I* | Annex I | - -*_This edition featured inconsistent lettering._ - -## A.5 Differences from V2.2 and V2.1 - -- JSON, YAML, and a development version of XML have been added as supported file formats. - -- A new appendix "SPDX File Tags" has been added to describe a method that developers can use to document other SPDX file-specific information (such as copyright notices, file type, etc.) in a standardized and easily machine-readable manner. See Appendix IX for more information. - -- A new appendix "SPDX Lite" has been added to document a lightweight subset of the SPDX specification for scenarios where a full SPDX document is not required. See Appendix VIII for more information. - -- Additional relationship options have been added to enable expression of different forms of dependencies between SPDX elements. As well, NONE and NOASSERTION keywords are now permitted to be used with relationships to indicate what is unknown. - -- Miscellaneous bug fixes and non-breaking improvements as reported on the mailing list and reported as issues on the spdx-spec GitHub repository. - -## A.6 Differences between V2.1 and V2.0 - -- Snippets have been added to allow a portion of a file to be identified as having different properties from the file it resides in. The use of snippets is completely optional and it is not mandatory for snippets to be identified. See section 5 Snippet Information for further details on the fields available to describe snippets. - -- External Packages can now be referred to in SPDX documents. When there is no SPDX file information available to document the content of these external packages, then the filesAnalyzed attribute on a package should be set to false. See section 3.8 Files Analyzed for more information. - -- Packages are now able to associate with an “External Reference” which allows a Package to reference an external source of additional information, metadata, enumerations, asset identifiers, or downloadable content believed to be relevant to the Package. See: section 3.21 External Reference, 3.22 External Reference Comment and Appendix VI: External Repository Identifiers for more information. - -- The “Artifact of Project” fields at the file level are now deprecated, as they can be replaced by a relationship to the more descriptive External Packages. - -- A new appendix “Using SPDX short identifiers in Source Files” has been added to document the best practices to refer to the licenses in the SPDX license list that have emerged from the development community. See Appendix V: Using SPDX short identifiers in Source Files for more information. - -- Miscellaneous bug fixes. - -## A.7 Differences between V2.0 and V1.2 - -- Abstraction has been applied to the underlying model with the inclusion of SPDX elements. With SPDX 2.0, the concept of an SPDX element is introduced (see Appendix III). This includes SPDX documents, SPDX files, and SPDX packages, each of which gets associated with an SPDX identifier which is denoted by “SPDXRef-”. - -- SPDX relationships have been added to allow any SPDX element to have a relationship to other SPDX elements. Documented the origin of an SPDX hierarchy of sub-packages, documenting the origin of an SPDX element, and documenting modifications or corrections (annotations) to an SPDX element. - -- The ability to reference SPDX elements outside the current SPDX document itself (external references). - -- Additional file types are now supported. - -- Additional checksum algorithms are now supported. - -- Review Information section is deprecated. It is recommended to provide document reviews with Annotations (Section 7). - -- A License Expression Syntax has been introduced and documented in Appendix IV. diff --git a/docs/annexes/getting-started.md b/docs/annexes/getting-started.md deleted file mode 100644 index f7e076f008..0000000000 --- a/docs/annexes/getting-started.md +++ /dev/null @@ -1,740 +0,0 @@ -# Annex B: Getting started writing SPDX 3 (Informative) -## (a.k.a My First SPDX File) - -This guide is designed to walk you through the concepts behind an SPDX -document, by walking through writing one by hand. While it is possible to write -all your SPDX documents by hand, we would recommend looking at the various -language bindings that are available for crafting more complex documents. -Nevertheless, walking through an example of a hand written document can be -instructive into how SPDX documents work to better understand concepts that are -at play, even when using language bindings. - -All of the provided fragments listed here are intended to be used to construct -a complete a valid SPDX JSON document when concatenated together - -If you do would like to construct the complete example from this Markdown file, -use the following command: - -```shell -cat getting-started.md | awk 'BEGIN{flag=0} /^```json/, $0=="```" { if (/^---$/){flag++} else if ($0 !~ /^```.*/ ) print $0 > "doc-" flag ".spdx.json"}' -``` - -Please note that all descriptions of properties, classes, etc. are -non-normative; that is they are intended to help you understand what is going -on in simpler language, but are not necessarily complete. Links to the full -official documentation are provided where possible. - -## The Preamble - -All documents need to start somewhere, and SPDX documents are no exception. - -The root of all SPDX documents will be a JSON object, so start with that: -```json -{ -``` - -Next, we need to identify that the document is an SPDX 3 JSON-LD document, which is done with: -```json - "@context": "https://spdx.org/rdf/3.0.0/spdx-context.jsonld", -``` -SPDX documents are designed to be a strict subset of [JSON-LD][1], such that -they can be parsed using either a full JSON-LD parser if you need the full -power of [linked documents][2] or [RDF][3], or a much simpler JSON parser if -all you care about is extracting meaningful SPDX data from the document. - -Because the document is valid JSON-LD, the `@context` must be provided to tell -the JSON-LD parser how to expand the human readable names in the document into -full IRIs (don't worry if you don't know what that means, it's not really that -important). You can think of this line as telling us "This is an SPDX document, -and this provided URL tells us how to decode it". The [SPDX JSON -Schema][spdxjsonschema] will force you to put the correct value here when -validating a document. - - -Now, we need to specify the list of objects that we want to create in this -document. JSON-LD has a special way of specifying this list using the `@graph` -property of the root object like so: -```json - "@graph": [ -``` - - -## Tell us about yourself - -Our first SPDX object is going to be a [Person][Class_Person] that tells us who -is writing this document (you!), so lets get started with it: - -```json - { - "type": "Person", -``` - -This is the basic format for any object in SPDX; all objects have one required -property named `type` that tells us what this object actually is, so here we -say this is a [Person][Class_Person]. - -Next, we need to name our object: -```json - - "spdxId": "http://spdx.org/spdxdocs/Person/JoshuaWatt-141ec767-40f2-4aad-9658-ac2703f3a7d9", -``` - -Most objects can have some sort of "ID" property that gives it a name. In the -case of [Person][Class_Person], that property is called `spdxId` (inherited -from [Element][Class_Element]). This property is the URI that should give this -object a universally unique name. Although this property _looks_ like a HTTP -URL, it is in fact not. Technically speaking, a URL defined a _Location_, where -as a URI defines an _Identifier_ (i.e. the name by which something is known). -In all likelihood, a URI is not a resolvable location from whence you can do an -HTTP `GET` to retrieve data, but rather just a way of constructing a namespaced -identifier. This identifier can be used within this document to refer to this -object (more on that later), or it can be referenced from other documents to -refer to this _specific_ object (although in that case there needs to be -additional information to describe how to find this document). URI's are -considered to be universally unique, so any objects constructed with this URI -are considered to be the same object, and any references to this URI is a -reference to this _specific_ object we are creating. - -If you work for a company, own a domain, etc. it is encouraged to use that (or -some subdomain of it) in place of `spdx.org/spdxdocs`. - -In practice, many `spdxId` values will have some sort of hash or random -UUID-like string incorporated to make them unique. - -Moving on from this, we have: -```json - "creationInfo": "_:creationinfo", -``` - -All SPDX objects derived from [Element][Class_Element] _must_ specify how they -were created by _linking_ to a [CreationInfo][Class_CreationInfo] object. It is -important to know the providence of where objects come from; but more on this -later. - -```json - "name": "Joshua Watt", -``` - -The optional [name][Property_name] property is inherited from the `Element` -class, and means "the common name for the thing", or in this case, your name. - -As our last step, we want to indicate another way by which You are known to the -world; specifically your E-mail address. - -To do this we first need to use the (optional) -[externalIdentifier][Property_externalIdentifier] property which -[Person][Class_Person] inherits from [Element][Class_Element]: - -```json - "externalIdentifier": [ -``` - -This property is an array of [ExternalIdentifier][Class_ExternalIdentifier] -objects, so start by adding one to the array: - -```json - { - "type": "ExternalIdentifier", -``` - -Again notice this uses the `type` property to identify what the object is. -However it should be noted that this is our first object that is not derived -from [Element][Class_Element], and therefore it does not need a `spdxId` -property. - -Next, lets add the relevant information about your email address: - -```json - "externalIdentifierType": "email", - "identifier": "JPEWhacker@gmail.com" -``` - -Two properties are used here. First, -[externalIdentifierType][Property_externalIdentifierType] is used to indicate -what type of external identifier this is. There are many choices, but in the -case we are specifying your email address, so we choose the value `email`. The -second property is the [indentifier][Property_identifier] property which is the -actual string identifier (in this case, your email address). - - -We are now done with our [Person][Class_Person], so close it all out and -prepare for the next object: - -```json - } - ] - }, -``` - - -## Where did all this stuff come from? - -Our next object is going to be a [CreationInfo][Class_CreationInfo] object. It -is required to provide one for every SPDX document, as all objects derived from -[Element][Class_Element] must link to one in their -[creationInfo][Property_creationInfo] property to indicate where they came -from. - -Note that the [CreationInfo][Class_CreationInfo] describes where a SPDX -[Element][Class_Element] itself came from (that is, who wrote the actual JSON). -This is a distinct concept from describing where the thing an -[Element][Class_Element] _describes_ comes from, which is covered later. - -Lets get started: -```json - { - "type": "CreationInfo", -``` -Hopefully this is making sense. We are saying this object is a -[CreationInfo][Class_CreationInfo]. - -```json - "@id": "_:creationinfo", -``` - -This object also has an `@id` similar to the `spdxId` of our person, but it is -subtly different First of all, this one is _not_ a URI like our -[Person][Class_Person], but instead starts with a `_:`. This type of identifier -is known as a _blank node_. Blank nodes serve a similar purpose to the URI of -the `spdxId`, however they _only_ have scope within this SPDX document. What -this means is that it be impossible to reference this -[CreationInfo][Class_CreationInfo] by name outside of this document. Inside the -document, you can use this identifier to refer to this object. The string after -the `_:` is arbitrary and you may choose whatever unique (within the document) -string that you choose. - -It should be noted that [CreationInfo][Class_CreationInfo] does _not_ derive -from [Element][Class_Element] class (like our previous example of -[ExternalIdentifier][Class_ExternalIdentifier]), and as such the `@id` property -is technically optional. However, since we will need to refer to this object at -other places in the document, we must give it an identifier. This also means -that this object does not have a mandatory -[creationInfo][Property_creationInfo] property (which makes sense since it -would be a circular reference). Finally, [CreationInfo][Class_CreationInfo] is -_only_ allowed to have a blank node identifier. - -If you look back at the [Person][Class_Person] we just created, you'll notice -that its [creationInfo][Property_creationInfo] property has the string value -that matches the `@id` of this object; this is how objects are linked together -by reference in SPDX. - -Next, we need to specify which version of the SPDX spec that elements linking -to this [CreationInfo][Class_CreationInfo] are conforming to: - -```json - "specVersion": "3.0.0", -``` - -Now, we need to use the [createdBy][Property_createdBy] property to indicated -who (or what) created the elements that are linked to this -[CreationInfo][Class_CreationInfo]: - -```json - "createdBy": [ - "http://spdx.org/spdxdocs/Person/JoshuaWatt-141ec767-40f2-4aad-9658-ac2703f3a7d9" - ], -``` - -This property is a list of reference to any class that derives from -[Agent][Class_Agent]. Since you are the person writing the document, put a -single list item that is the `spdxId` of your [Person][Class_Person] element -here to link them together. Note that even though this is using a full URI -instead of a blank node, this is linking in the same way as -[creationInfo][Property_creationInfo] described above. - -Also, it is worth noting that this does indeed create a circular reference -between our [Person][Class_Person].[creationInfo][Property_creationInfo] -property and [CreationInfo][Class_CreationInfo].[createdBy][Property_createdBy] -property. This is fine in SPDX, as objects are not required to be a Directed -Acyclical Graph (DAG). - - -Finally, we need to specify the date that any objects linking to this -[CreationInfo][Class_CreationInfo] were created using the -[created][Property_created] property and close out the object: - -```json - "created": "2024-03-06T00:00:00Z" - }, -``` - -Use today's date and time in [ISO 8601][4] with the format: -`"%Y-%m-%dT%H:%M:%SZ"`. The timezone should always be UTC. - - -## Describing the Document - -SPDX requires that information about the document itself be provided. In order -to do this, we must create a [SpdxDocument][Class_SpdxDocument] object, so lets -do that now: - -```json - { - "type": "SpdxDocument", - "spdxId": "https://spdx.org/spdxdocs/Document1-d078aed9-384d-4a64-87cb-99c79647c8c9", - "creationInfo": "_:creationinfo", -``` - -[SpdxDocument][Class_SpdxDocument] derives from [Element][Class_Element], so it -has 3 required properties, `type`, `spdxId` and -[creationInfo][Property_creationInfo]. We've seen all of these properties -before in [Person][Class_Person], so hopefully this getting more familiar. Note -that we again link back out our previous [CreationInfo][Class_CreationInfo] -object. - -Next, we need to indicate which [Profiles][SPDX_Profile] our document uses -using the [profileConformance][Property_profileConformance] property. This can -be used by consumers of the document to quickly determine if the information -they want is in the document (for example, if a user wants to find CVE data, -but the `security` profile is not present, there is no reason to continue -looking in this document). - -```json - "profileConformance": [ - "core", - "software" - ], -``` - -In this case, we are saying this document conforms to the `core` profile (all -SPDX documents should include this), and the `software` profile, since we will -be describing some software later. - -The final property we need to define is [rootElement][Property_rootElement]. -This property is a list of [Element][Class_Element] (or any subclass of -Element) references. Add this now and close our our -[SpdxDocument][Class_SpdxDocument]: - -```json - "rootElement": [ - "https://spdx.org/spdxdocs/BOM-e2e955f5-c50e-4a3a-8c69-db152f0f4615" - ] - }, -``` - -The purpose of this property is to indicate the "interesting" element(s) in the -document. Since a document can contain a large number of elements, it might be -difficult for a consumer of the document to know what the focus of the document -is. This property clarifies that by suggesting which element(s) a user should -look at to start navigating. While it is possible to have more than one root -element, it is rare to need more than one. - -Careful readers of the [SpdxDocument][Class_SpdxDocument] documentation will -note that we have omitted the [element][Property_element] (derived from the -[ElementCollection][Class_ElementCollection] parent class). Technically -speaking, the property _should_ link to all the elements that are in the -document using this property. However because this would be error prone, it is -implied that all [Element][Class_Element] objects present in the `@graph` (that -is, all the objects we are writing) are implicitly added to the -[element][Property_element] property. - -## A Complete Document! - -At this point, we have a completed SPDX document (albeit, one that has an -unresolved references in -[SpdxDocument][Class_SpdxDocument].[rootElement][Property_rootElement]). This -is a fully valid document because it has the SPDX 3.0 preamble, and the -required [SpdxDocument][Class_SpdxDocument] object, which in turn requires a -valid [CreationInfo][Class_CreationInfo], which we've provided. Finally, the -[CreationInfo][Class_CreationInfo] requires an [Agent][Class_Agent] to describe -who or what created the Elements in the document, which we've provided by -writing a [Person][Class_Person] object which describes you. - -While this is the minimal example, it may feel long. However, as we continue in -the document it should become more apparent how reuse of these 3 objects -(particularly the [CreationInfo][Class_CreationInfo]) helps _reduce_ total -document size while still conveying precise information. In addition, there are -other options to make a more compact document that are not covered yet, such as -referring to a external [Agent][Class_Agent] instead of encoding it in the -document. - -## Lets Add Some Software! - -Now that we have the basic valid document, its time to start adding some -interesting data to it. Lets start with a fictitious software package called -`amazing-widget` which we distribute as a tarball for users to download and run. - -To start with, we need to define a [software_Package][Class_software_Package] -object the defines how our software is distributed. In this case, the -[software_Package][Class_software_Package] will be describing a tarball which -someone can download, but it can be almost any unit of content that can be used -to distribute software (either as binaries or source). See the documentation -for more details. - -Lets define our package: -```json - { - "type": "software_Package", - "spdxId": "https://spdx.org/spdxdocs/Package-d1db6e61-aebe-4b13-ae73-d0f66018dbe0", - "creationInfo": "_:creationinfo", -``` -This should be familiar by now. Note the reuse of our previous -[CreationInfo][Class_CreationInfo]. - -Also note that this is our first element that is outside of the `Core` profile -in SPDX. In this specific case, the class is defined in the `Software` profile, -and as such is prefixed with `software_`. Any classes and properties that are -defined in a profile other than `Core` will be prefixed with the lower case -profile name + `_` to disambiguate them from classes and properties with the -same name in other profiles. - -Again, we can use [Element][Class_Element].[name][Property_name] to give the -common name for our package: - -```json - "name": "amazing-widget", -``` - -Importantly, even though this is a class defined in the `Software` profile, -[name][Property_name] is defined in core so it _does not_ get prefixed. When -writing objects, pay attention to which profile the _property_ is defined in, -as that sets the prefix (the documentation should make it clear what the -serialized name of a property is if you are unsure *TODO: It does not yet*). - -Next, we will define what version the `amazing-widget` package is using -[software_packageVersion][Property_software_packageVersion], and where the user -could download this package from using -[software_downloadLocation][Property_software_downloadLocation] (both are -optional): - -```json - "software_packageVersion": "1.0", - "software_downloadLocation": "http://dl.example.com/amazing-widget_1.0.0.tar", -``` - -These are our first two examples of properties not defined in the `Core` -profile, and as such they get the `software_` prefix. - - -Now, we should define when this software was packaged using the (optional) -[builtTime][Property_builtTime] property, so that downstream users can tell how -old it is: - -```json - "builtTime": "2024-03-06T00:00:00Z", -``` - -Note that we are back in the `Core` profile properties here (specifically, -[builtTime][Property_builtTime] is a property of [Artifact][Class_Artifact] in -`Core`) - - -Next, we want to indicate who actually made the package we are describing. This -is done using the (optional) [originatedBy][Property_originatedBy] array -property: - -```json - "originatedBy": [ - "http://spdx.org/spdxdocs/Person/JoshuaWatt-141ec767-40f2-4aad-9658-ac2703f3a7d9" - ], -``` - -In this example, you can put a single element that references your -[Person][Class_Person] `spdxId` here to indicate that _you_ actually made the -package. Note that while we are using the same `spdxId` as we used in the -[CreationInfo][Class_CreationInfo], this is not required. -[originatedBy][Property_originatedBy] is the property that we used to describe -who made the actual package being described by the -[software_Package][Class_software_Package] and not the JSON object itself. - -Finally, we would like to inform consumers of our SPDX how they can validate -the package to ensure its contents have not changed, or to check if a file that -they have is the same one being described by this document. This is done using -the [verifiedUsing][Property_verifiedUsing] property, which is an array of -[IntegrityMethod][Class_IntegrityMethod] objects (or subclasses). - -```json - "verifiedUsing": [ - { - "type": "Hash", - "algorithm": "sha256", - "hashValue": "f3f60ce8615d1cfb3f6d7d149699ab53170ce0b8f24f841fb616faa50151082d" - } - ] - }, -``` - -Specifically, we are using the [Hash][Class_Hash] subclass of integrity method to -indicate that the SHA-256 checksum of the package file is -`f3f60ce8615d1cfb3f6d7d149699ab53170ce0b8f24f841fb616faa50151082d` - - -## Whats in our Package? - -Describing that we have a distributed package is a great start, but we are able -to go further (although this is not mandatory!). Our next object is going to -describe all the files contained in our -[software_Package][Class_software_Package] by using -[software_File][Class_software_File]. - -Lets get started with our first file, the program executable: - -```json - { - "type": "software_File", - "spdxId": "https://spdx.org/spdxdocs/File-8f79956e-4089-4166-9a71-457de77e4846", - "creationInfo": "_:creationinfo", - "name": "/usr/bin/amazing-widget", - "verifiedUsing": [ - { - "type": "Hash", - "algorithm": "sha256", - "hashValue": "ee4f96ed470ea288be281407dacb380fd355886dbd52c8c684dfec3a90e78f45" - } - ], - "builtTime": "2024-03-05T00:00:00Z", - "originatedBy": [ - "http://spdx.org/spdxdocs/Person/JoshuaWatt-141ec767-40f2-4aad-9658-ac2703f3a7d9" - ], -``` - -We've seen all this before, so hopefully it all makes sense. - -While it's great to have a file, it's not easy to tell what purpose this file -serves. We might be able to infer that its an executable program from the -[name][Property_name], but SPDX provides the ability for us to directly specify -this using the (optional) -[software_primaryPurpose][Property_software_primaryPurpose] and -[software_additionalPurpose][Property_software_additionalPurpose] properties -(derived from [sofware_Artifact][Class_software_Artifact]): - -```json - "software_primaryPurpose": "executable", - "software_additionalPurpose": [ - "application" - ], -``` - -A [software_Artifact][Class_software_Artifact] can have as many purposes a you -want to describe, but there should always be a -[software_primaryPurpose][Property_software_primaryPurpose] property defined -before any [software_additionalPurpose][Property_software_additionalPurpose] -are added. - -Finally, as one last bit of information, we'll say what the copyright text of -the program is using the (optional) -[software_copyrightText][Property_software_copyrightText] property and close -out our file: - -```json - "software_copyrightText": "Copyright 2024, Joshua Watt" - }, -``` - -Lets add one more file for fun. This one will describe a config file for our -program: - -```json - { - "type": "software_File", - "spdxId": "https://spdx.org/spdxdocs/File-77808a5c-7a1b-43d1-9fa9-410a309ca9f3", - "creationInfo": "_:creationinfo", - "name": "/etc/amazing-widget.cfg", - "verifiedUsing": [ - { - "type": "Hash", - "algorithm": "sha256", - "hashValue": "89a2e80bc48c4dd10044c441af0fc6fdad5d31b2fa391cb2cf9c51dbf4200ed9" - } - ], - "builtTime": "2024-03-05T00:00:00Z", - "originatedBy": [ - "http://spdx.org/spdxdocs/Person/JoshuaWatt-141ec767-40f2-4aad-9658-ac2703f3a7d9" - ], - "software_primaryPurpose": "configuration" - }, -``` - -## Linking things together with Relationships - -Now we've described our [software_Package][Class_software_Package], and two -[software_File][Class_software_File]s that should be contained in it, but we -have one small problem: there is nothing that tells us that our files are -actually contained by the package. - -In order to do this, we must introduce the SPDX -[Relationship][Class_Relationship]. These are a very powerful concept in SPDX -that allows linking [Element][Class_Element]s and describing how they are -related. - -[Relationship][Class_Relationship]s themselves are also derived from SPDX -[Element][Class_Element]s, so we need the required three properties to start a -new one: - -```json - { - "type": "Relationship", - "spdxId": "https://spdx.org/spdxdocs/Relationship/contains-6b0b7ce4-a069-406d-9088-9e91f65b79f0", - "creationInfo": "_:creationinfo", -``` - -Next, we need to say what the relationship between our objects is going to be. -We do this using the [relationshipType][Property_relationshipType] property: - -```json - "relationshipType": "contains", -``` - -The full list of what a [Relationship][Class_Relationship] can describe is -defined by the [RelationshipType][Vocab_RelationshipType] vocabulary (a fancy -work for enumeration). There are a lot of possible options, and each one has a -specific meaning and restrictions on what types it can relate, so read the -documentation to find the specific one you need and how to use it. In our case, -we are using `contains` which is defined as "The `from` -[Element][Class_Element] contains each `to` [Element][Class_Element]". Perfect. - -Now, we need to describe what [Element][Class_Element]s are being connected. -[Relationship][Class_Relationship]s always have a directionality associated -with them: you can think of them as an arrow pointing from their -[from][Property_from] property to their [to][Property_to] properties. -[from][Property_from] is always required and must be a single object, whereas -[to][Property_to] is a list of zero or more objects. Lets write the JSON to -express this: - -```json - "from": "https://spdx.org/spdxdocs/Package-d1db6e61-aebe-4b13-ae73-d0f66018dbe0", - "to": [ - "https://spdx.org/spdxdocs/File-8f79956e-4089-4166-9a71-457de77e4846", - "https://spdx.org/spdxdocs/File-77808a5c-7a1b-43d1-9fa9-410a309ca9f3" - ], -``` - -This is the minimum required to define a [Relationship][Class_Relationship], -but we want to add one more property to convey additional information and close -out the object: - -```json - "completeness": "complete" - }, -``` - -The [completeness][Property_completeness] property is very useful as it -indicates if we know that this [Relationship][Class_Relationship] can be -considered to describe all we know about the type of relationship or not. For -example, by stating that this relationship is `complete`, we are saying that -our package contains those 2 files, and _only_ those 2 files. We could have -also stated that the relationship was `incomplete` in which case we are stating -that we know we didn't list all the files, and other are included. -Alternatively, we could have stated that the relationship -[completeness][Property_completeness] was `noAssertion` meaning we don't know -if we captured all the files or not. If this property is omitted, it's assumed -to be `noAssertion`. - -## Wrapping it all up in a BOM - -We've made great progress, and we are _almost_ done. For our final step, we -want to wrap up everything we know about the package into a "Software Bill of -Materials". - -This is done by creating a [software_Sbom][Class_software_Sbom] object: - -```json - { - "type": "software_Sbom", - "spdxId": "https://spdx.org/spdxdocs/BOM-e2e955f5-c50e-4a3a-8c69-db152f0f4615", - "creationInfo": "_:creationinfo", -``` - -Note that this is the object referenced by the [rootElement][Property_rootElement] of -our [SpdxDocument][Class_SpdxDocument], since it is the primary subject of our entire -document. - -[software_Sbom][Class_software_Sbom] derives from -[ElementCollection][Class_ElementCollection] just like -[SpdxDocument][Class_SpdxDocument], so it has the same -[rootElement][Property_rootElement] property. In this case, it is the subject -of the SBOM, which is our [software_Package][Class_software_Package]: - -```json - "rootElement": [ - "https://spdx.org/spdxdocs/Package-d1db6e61-aebe-4b13-ae73-d0f66018dbe0" - ], -``` - -Unlike [SpdxDocument][Class_SpdxDocument] however, there is no implicit value -for the [element][Property_element] property. Instead, we need to list all the -elements that are part of this SBOM (think of this as the line items in the -SBOM). In our specific case, this is the [software_File][Class_software_File]s -that part of our package, but if you had any other elements related to the -package (e.g. licenses, security information, etc.) those would also be -included: - -```json - "element": [ - "https://spdx.org/spdxdocs/File-8f79956e-4089-4166-9a71-457de77e4846", - "https://spdx.org/spdxdocs/File-77808a5c-7a1b-43d1-9fa9-410a309ca9f3" - ], -``` - -Finally, we need to specify what type(s) of BOM this is using the -[software_sbomType][Property_software_sbomType] property: - -```json - "software_sbomType": [ - "build" - ] - } -``` - -This property is effectively indicating at what point in the software lifecycle -this SBOM was generated. Since we are describing an executable program, `build` -seems the most likely. - -## Closing it all up - -Now that we are all done, we have a few things to clean up, namely that we need -to close the `@graph` list and the root object, so lets do that now: - -```json - ] -} -``` - -**Congratulations!** You just wrote your first SPDX document! Hopefully this -walk through has been instructive and you are ready to get started with SPDX! - -[1]: https://json-ld.org/ -[2]: https://en.wikipedia.org/wiki/Linked_data -[3]: https://www.w3.org/RDF/ -[4]: https://en.wikipedia.org/wiki/ISO_8601 -[spdxjsonschema]: https://spdx.org/schema/3.0.0/spdx-json-schema.json -[Class_Agent]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Agent -[Class_Artifact]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Artifact -[Class_CreationInfo]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/CreationInfo -[Class_ElementCollection]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/ElementCollection -[Class_Element]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element -[Class_ExternalIdentifier]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/ExternalIdentifier -[Class_Hash]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Hash -[Class_IntegrityMethod]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/IntegrityMethod -[Class_Person]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Person -[Class_Relationship]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Relationship -[Class_SpdxDocument]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/SpdxDocument -[Class_software_Artifact]: https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/Artifact -[Class_software_File]: https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/File -[Class_software_Package]: https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/Package -[Class_software_Sbom]: https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/Sbom -[Property_builtTime]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/builtTime -[Property_completeness]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/completeness -[Property_createdBy]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/createdBy -[Property_created]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/created -[Property_creationInfo]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/creationInfo -[Property_element]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/element -[Property_externalIdentifier]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/externalIdentifier -[Property_externalIdentifierType]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/externalIdentifierType -[Property_from]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/from -[Property_identifier]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/identifier -[Property_name]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/name -[Property_originatedBy]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/originatedBy -[Property_profileConformance]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/profileConformance -[Property_relationshipType]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/relationshipType -[Property_rootElement]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/rootElement -[Property_software_additionalPurpose]: https://spdx.github.io/spdx-spec/v3.0/model/Software/Properties/additionalPurpose -[Property_software_copyrightText]: https://spdx.github.io/spdx-spec/v3.0/model/Software/Properties/copyrightText -[Property_software_downloadLocation]: https://spdx.github.io/spdx-spec/v3.0/model/Software/Properties/downloadLocation -[Property_software_packageVersion]: https://spdx.github.io/spdx-spec/v3.0/model/Software/Properties/packageVersion -[Property_software_primaryPurpose]: https://spdx.github.io/spdx-spec/v3.0/model/Software/Properties/primaryPurpose -[Property_software_sbomType]: https://spdx.github.io/spdx-spec/v3.0/model/Software/Properties/sbomType -[Property_to]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/to -[Property_verifiedUsing]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/verifiedUsing -[SPDX_Profile]: https://spdx.github.io/spdx-spec/v3.0/ -[Vocab_RelationshipType]: https://spdx.github.io/spdx-spec/v3.0/model/Core/Vocabularies/RelationshipType diff --git a/docs/annexes/including-security-information-in-SPDX.md b/docs/annexes/including-security-information-in-SPDX.md deleted file mode 100644 index 95ea0878c3..0000000000 --- a/docs/annexes/including-security-information-in-SPDX.md +++ /dev/null @@ -1,401 +0,0 @@ -# Annex G: Including Security Information in a SPDX document - -The flexibility of SPDX 3.0 allows users to either link SBOMs to external security vulnerability data or to embed security vulnerability information in the SPDX 3.0 data format. For more details about the differences, read ["Capturing Software Vulnerability Data in SPDX 3.0"](https://spdx.dev/capturing-software-vulnerability-data-in-spdx-3-0/). - -## G.1 External References and External Identifiers -SPDX 3.0 has the concept of an [__External Reference__](https://github.com/spdx/spdx-3-model/blob/main/model/Core/Classes/ExternalRef.md) for an Element which points to a general resource outside the scope of the SPDX-3.0 content that provides additional context or information about an Element. - -The specification for External Reference types has many [type options](https://github.com/spdx/spdx-3-model/blob/main/model/Core/Vocabularies/ExternalRefType.md), a large handful of which pertain specifically to security use cases: - -* cwe -* secureSoftwareAttestation -* securityAdvisory -* securityAdversaryModel -* securityFix -* securityOther -* securityPenTestReport -* securityPolicy -* securityThreatModel -* vulnerabilityDisclosureReport -* vulnerabilityExploitabilityAssessment - - -SPDX 3.0 also has the concept of [__External Identifier__](https://github.com/spdx/spdx-3-model/blob/main/model/Core/Classes/ExternalIdentifier.md) which should be used in cases where an identifier scheme exists and is already defined for an Element outside of SPDX-3.0. - -There are several External Identifier [types](https://github.com/spdx/spdx-3-model/blob/main/model/Core/Vocabularies/ExternalIdentifierType.md) that may be used in a security context: - -* cpe22 -* cpe23 -* cve -* packageUrl -* securityOther - - -This section provides usage scenarios of how to leverage the Security External References and External Identifiers specified above to refer to external security information. Examples of how to use each category can be found in the [Security/Classes](https://github.com/spdx/spdx-3-model/tree/main/model/Security/Classes) pages. Multiple instances and types of external security information may be included within a SPDX document. - -## G.1.1 Linking to an Advisory - -To reference a Common Vulnerabilities and Exposures (CVE) advisory applicable to a package, you must first create a [Vulnerability Element](https://github.com/spdx/spdx-3-model/blob/main/model/Security/Classes/Vulnerability.md). You can then use ExternalIdentifiers or ExternalRefs to supplement the CVE with associated external metadata. - -```json -{ - "type": "security_Vulnerability", - "spdxId": "urn:spdx.dev:cve-2020-2849", - "creationInfo": "_:creationInfo", - "summary": "Use of a Broken or Risky Cryptographic Algorithm", - "description": "The npm package `elliptic` before version 6.5.4 are vulnerable to Cryptographic Issues via the secp256k1 implementation in elliptic/ec/key.js. There is no check to confirm that the public key point passed into the derive function actually exists on the secp256k1 curve. This results in the potential for the private key used in this implementation to be revealed after a number of ECDH operations are performed.", - "security_modifiedTime": "2021-03-08T16:06:43Z", - "security_publishedTime": "2021-03-08T16:02:50Z", - "externalIdentifier": [ - { - "type": "ExternalIdentifier", - "externalIdentifierType": "cve", - "identifier": "CVE-2020-2849", - "identifierLocator": [ - "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-28498", - "https://www.cve.org/CVERecord?id=CVE-2020-28498" - ], - "issuingAuthority": "urn:spdx.dev:agent-cve.org" - }, - { - "type": "ExternalIdentifier", - "externalIdentifierType": "securityOther", - "identifier": "GHSA-r9p9-mrjm-926w", - "identifierLocator": ["https://github.com/advisories/GHSA-r9p9-mrjm-926w"] - } - ], - "externalRef": [ - { - "type": "ExternalRef", - "externalRefType": "securityAdvisory", - "locator": ["https://nvd.nist.gov/vuln/detail/CVE-2020-28498"] - }, - { - "type": "ExternalRef", - "externalRefType": "securityAdvisory", - "locator": ["https://ubuntu.com/security/CVE-2020-28498"] - }, - { - "type": "ExternalRef", - "externalRefType": "securityOther", - "locator": ["https://github.com/indutny/elliptic/pull/244/commits"] - } - ] -}, -``` - -## G.1.2 Linking to a CSAF Document - -To reference [CSAF](https://docs.oasis-open.org/csaf/csaf/v2.0/cs01/csaf-v2.0-cs01.html) formatted security information see below for examples. - -### G.1.2.1 Linking to a CSAF VEX -To reference a CSAF VEX document, include an external reference of type `vulnerabilityExploitabilityAssessment` on the Vulnerability Element that encapsulates the CVE described in the CSAF VEX document. - - -```json -{ - "type": "security_Vulnerability", - "spdxId": "urn:spdx.dev:vuln-2", - "creationInfo": "_:creationInfo", - "name": "cve-2021-44228", - "description": "Apache Log4j2 2.0-beta9 through 2.15.0 (excluding security releases 2.12.2, 2.12.3, and 2.3.1) JNDI features used in configuration, log messages, and parameters do not protect against attacker controlled LDAP and other JNDI related endpoints. An attacker who can control log messages or log message parameters can execute arbitrary code loaded from LDAP servers when message lookup substitution is enabled.", - "security_modifiedTime": "2021-03-08T16:02:43Z", - "security_publishedTime": "2021-03-08T16:06:50Z", - "externalIdentifier": [ - { - "type": "ExternalIdentifier", - "externalIdentifierType": "cve", - "identifier": "CVE-2021-44228", - "identifierLocator": [ - "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-44228", - "https://www.cve.org/CVERecord?id=CVE-2021-44228" - ], - "issuingAuthority": "http://spdx.dev/agent-cve.org" - } - ], - "externalRef": [ - { - "type": "ExternalRef", - "externalRefType": "vulnerabilityExploitabilityAssessment", - "locator": ["https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/examples/csaf/csaf_vex/2022-evd-uc-01-a-001.json"] - } - ] -}, -``` - -### G.1.2.2 Linking to a CSAF Advisory -To reference a CSAF Advisory document, include the document locator as an external reference of type `securityAdvisory` on a Package Element. - -```json -{ - "type": "software_Package", - "spdxId": "urn:spdx.dev:pkg-rh-open-shift", - "creationInfo": "_:creationInfo", - "name": "Red Hat OpenShift Enterprise", - "software_packageVersion": "3.6", - "externalRef": [ - { - "type": "ExternalRef", - "externalRefType": "securityOther", - "locator": ["https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/examples/csaf/rhsa-2019_1862.json"] - } - ] -}, -``` - - -## G.1.3 Linking to CycloneDX Security Data - -To reference to [CycloneDX](https://cyclonedx.org) formatted security information applicable to a package you need to first create a Package Element. - -Using an External Reference, link the package to the matching component in the CycloneDX BOM. Link to it using its [BOM link](https://cyclonedx.org/capabilities/bomlink/), a URN formed by combining the CycloneDX serial number, version and bom-ref which contains the security information about the package. - -```json -{ - "type": "software_Package", - "spdxId": "urn:spdx.dev:pkg-stack-cors", - "creationInfo": "_:creationInfo", - "name": "stack-cors", - "software_packageVersion": "1.3.0", - "externalRef": [ - { - "type": "ExternalRef", - "externalRefType": "securityOther", - "locator": ["https://cyclonedx.org/capabilities/bomlink/17cfc349-c637-4685-856c-81196420c7f5/2#componentRef"] - } - ] -}, -``` - -## G.1.4 Linking to an OSV - -To include a reference to [Open Source Vulnerability](https://github.com/google/osv) (OSV) formatted security information applicable to a package you need to first create a Package Element. Then use an External Reference to link to the OSV advisory. - -```json -{ - "type": "software_Package", - "spdxId": "urn:spdx.dev:pkg-Django", - "creationInfo": "_:creationInfo", - "name": "Django", - "software_packageVersion": "2.2", - "externalRef": [ - { - "type": "ExternalRef", - "externalRefType": "securityAdvisory", - "locator": ["https://github.com/github/advisory-database/blob/6b9d5bc96a62bb845ee71e4551a214eb1457e2c6/advisories/github-reviewed/2022/04/GHSA-2gwj-7jmv-h26r/GHSA-2gwj-7jmv-h26r.json"] - } - ] -}, -``` - - -## G.1.5 Linking to an OmniBOR (formerly known as GitBOM) - -To identify a Package with an [OmniBOR](https://omnibor.io/) (Universal Bill Of Receipts, formerly known as GitBOM) gitoid, use an External Identifier to add gitoid to the package. - - -```json -{ - "type": "software_Package", - "spdxId": "urn:spdx.dev:pkg-example", - "creationInfo": "_:creationInfo", - "name": "Example", - "software_packageVersion": "1.2.3", - "externalIdentifier": [ - { - "type": "ExternalIdentifier", - "externalIdentifierType": "gitoid", - "identifier": "gitoid:blob:sha1:bcb99b819dadaebdf2c8f88d92ee9024c45f9df3" - } - ] -}, -``` - -## G.1.6 Linking to a vulnerability disclosure document - -To express a reference to a vulnerability disclosure document for a package, use an External Reference for a Package Element. The example below shows Cisco’s response to Apache log4j vulnerability. - -```json -{ - "type": "software_Package", - "spdxId": "urn:spdx.dev:pkg-apache-log4j", - "creationInfo": "_:creationInfo", - "name": "log4j", - "software_packageVersion": "2.14.0", - "externalRef": [ - { - "type": "ExternalRef", - "externalRefType": "securityAdvisory", - "locator": ["https://sec.cloudapps.cisco.com/security/center/content/CiscoSecurityAdvisory/cisco-sa-apache-log4j-qRuKNEbd"] - } - ] -}, -``` - -To communicate that a package is not vulnerable to a specific vulnerability it is recommended to reference a web page indicating why given vulnerabilities are not applicable using an External Reference on the package. - -```json -{ - "type": "software_Package", - "spdxId": "urn:spdx.dev:example-1", - "creationInfo": "_:creationInfo", - "name": "example", - "software_packageVersion": "1.0.0", - "externalRef": [ - { - "type": "ExternalRef", - "externalRefType": "securityAdvisory", - "locator": ["https://example.com/product-x/security-info-not-affected.html"] - } - ] -}, -``` - -To refer to a security disclosure feed, such as the security bulletins from [CERT-EU](https://cert.europa.eu), include an External Reference in the package Element. - - -```json -{ - "type": "software_Package", - "spdxId": "urn:spdx.dev:example-2", - "creationInfo": "_:creationInfo", - "name": "example", - "software_packageVersion": "2.0.0", - "externalRef": [ - { - "type": "ExternalRef", - "externalRefType": "securityAdvisory", - "locator": ["https://cert.europa.eu/cert/Data/newsletter/reviewlatest-SecurityBulletins.xml"] - } - ] -}, -``` - -## G.1.7 Linking to a Code Fix for a Security Issue - -You can include a reference to a code fix for a security issue applicable to a Package or Vulnerability Element. - -Using the Vulnerability Element from example 1.1 above or a Package Element, you would add a code fix External Reference to the Element as follows. In this example, the link points to a specific code revision containing the fix for [CVE-2020-28498](https://nvd.nist.gov/vuln/detail/CVE-2020-28498). - -```json -{ - "type": "software_Package", - "spdxId": "urn:spdx.dev:example-2", - "creationInfo": "_:creationInfo", - "name": "example", - "software_packageVersion": "2.0.0", - "externalRef": [ - { - "type": "ExternalRef", - "externalRefType": "securityFix", - "locator": ["https://github.com/indutny/elliptic/commit/441b7428b0e8f6636c42118ad2aaa186d3c34c3f"], - "comment": "elliptic before version 6.5.4 are vulnerable to Cryptographic Issues via the secp256k1 implementation in elliptic/ec/key.js. This patch fixes CVE-2020-28498." - } - ] -}, -``` - -A fix reference may point to a configuration change for example the patch file as one of the fixes for [CVE-2022-26499](https://nvd.nist.gov/vuln/detail/CVE-2022-26499). - -```json -{ - "type": "software_Package", - "spdxId": "urn:spdx.dev:example-2", - "creationInfo": "_:creationInfo", - "name": "example", - "software_packageVersion": "2.0.0", - "externalRef": [ - { - "type": "ExternalRef", - "externalRefType": "securityFix", - "locator": ["https://downloads.digium.com/pub/security/AST-2022-002-16.diff"] - } - ] -}, -``` - -Alternatively, it may also link to a landing page with patches for a variety of products such as Oracle patch information for [CVE-2021-44228](https://nvd.nist.gov/vuln/detail/CVE-2021-44228). - -```json -{ - "type": "software_Package", - "spdxId": "urn:spdx.dev:example-2", - "creationInfo": "_:creationInfo", - "name": "example", - "software_packageVersion": "2.0.0", - "externalRef": [ - { - "type": "ExternalRef", - "externalRefType": "securityFix", - "locator": ["https://www.oracle.com/security-alerts/cpujan2022.html"] - } - ] -}, -``` - - -## G.1.8 Linking to any Security Related Document - -If you want to reference any security information related to a package but cannot or do not wish to specify its kind, use the `securityOther` externalRefType. - -```json -{ - "type": "software_Package", - "spdxId": "urn:spdx.dev:pkg-elliptic", - "creationInfo": "_:creationInfo", - "name": "elliptic", - "software_packageVersion": "6.5.4", - "externalRef": [ - { - "type": "ExternalRef", - "externalRefType": "securityOther", - "locator": ["https://github.com/christianlundkvist/blog/blob/aa3a69b5e4c06e4435070610c0c4a2b1e8731783/2020_05_26_secp256k1_twist_attacks/secp256k1_twist_attacks.md"], - "comment": "Blog post from author who wrote fix for CVE-2020-28498." - } - ] -}, -``` - -One can also use it to refer to guidance related to a vulnerability such as CISA guidance for Apache Log4j. - -```json -{ - "type": "software_Package", - "spdxId": "urn:spdx.dev:pkg-apache-log4j", - "creationInfo": "_:creationInfo", - "name": "log4j", - "software_packageVersion": "2.14.0", - "externalRef": [ - { - "type": "ExternalRef", - "externalRefType": "securityOther", - "locator": ["https://www.cisa.gov/uscert/apache-log4j-vulnerability-guidance"] - } - ] -}, -``` - -## G.1.9 Linking to a Vulnerability Disclosure Report (VDR) - -The National Institute of Standards and Technology (NIST) describes the concept of correlating vulnerability and SBOM information for a software product at the component level in “[Software Security in Supply Chains: Software Bill of Materials (SBOM)](https://www.nist.gov/itl/executive-order-14028-improving-nations-cybersecurity/software-security-supply-chains-software-1)”. Use the External Reference `vulnerabilityDisclosureReport` type to report on vulnerabilities related to the components contained in a software product’s SBOM. - -This enables a software producer to articulate to software consumers the status of vulnerabilities contained in the software product, by means of reporting vulnerability information at either the SBOM document or component level. - -Providing a link to such data at the time the SBOM is published provides a pointer for where to find this relevant vulnerability information without promulgating vulnerability information inside the SBOM. This is advantageous because the vulnerability information has a short shelf-life (it will change frequently) while the SBOM component data isn’t likely to change if the software has not changed. - -```json -{ - "type": "software_Package", - "spdxId": "urn:spdx.dev:sag-pm", - "creationInfo": "_:creationInfo", - "name": "SAG-PM (TM)", - "software_packageVersion": "1.1.8", - "externalRef": [ - { - "type": "ExternalRef", - "externalRefType": "vulnerabilityDisclosureReport", - "locator": ["https://github.com/rjb4standards/REA-Products/blob/master/SBOM_and_VDRbaseline/sag-pm-118_VDR.json"] - } - ] -}, -``` diff --git a/docs/annexes/license-matching-guidelines-and-templates.md b/docs/annexes/license-matching-guidelines-and-templates.md index eec4c7ee0a..de3999242f 100644 --- a/docs/annexes/license-matching-guidelines-and-templates.md +++ b/docs/annexes/license-matching-guidelines-and-templates.md @@ -1,38 +1,38 @@ -# Annex C SPDX License List Matching Guidelines and Templates (Informative) +# SPDX License List Matching Guidelines and Templates (Normative) -## C.1 SPDX license list matching guidelines +## SPDX license list matching guidelines The SPDX License List Matching Guidelines provide guidelines to be used for the purposes of matching licenses and license exceptions against those included on the [SPDX License List](https://spdx.org/licenses/). There is no intent here to make a judgment or interpretation, but merely to ensure that when one SPDX user identifies a license as "BSD-3-Clause," for example, it is indeed the same license as what someone else identifies as "BSD-3-Clause" and the same license as what is listed on the SPDX License List. As noted here, some of the matching guidelines are implemented in the XML files of the SPDX License List repository. -## C.2 How these guidelines are applied +## How these guidelines are applied -### C.2.1 Purpose +### Purpose To ensure consistent results by different SPDX document creators when matching license information that will be included in the License Information in File field. SPDX document creators or tools may match on the license or exception text itself, the official license header, or the SPDX License List short identifier. -### C.2.2 Guideline: official license headers +### Guideline: official license headers The matching guidelines apply to license and exception text, as well as official license headers. Official license headers are defined by the SPDX License List as specific text specified within the license itself to be put in the header of files. (see [explanation of SPDX License List fields](https://github.com/spdx/license-list-XML/blob/master/DOCS/license-fields.md) for more info). The following XML tag is used to implement this guideline: `` -## C.3 Substantive text +## Substantive text -### C.3.1 Purpose +### Purpose To ensure that when matching licenses and exceptions to the SPDX License List, there is an appropriate balance between matching against the substantive text and disregarding parts of the text that do not alter the substantive text or legal meaning. Further guidelines of what can be disregarded or considered replaceable for purposes of matching are listed below here and in the subsequent specific guidelines. A conservative approach is taken in regard to rules relating to disregarded or replaceable text. -### C.3.2 Guideline: verbatim text +### Guideline: verbatim text License and exception text should be the same verbatim text (except for the guidelines stated here). The text should be in the same order, e.g., differently ordered paragraphs would not be considered a match. -### C.3.3 Guideline: no additional text +### Guideline: no additional text Matched text should only include that found in the vetted license or exception text. Where a license or exception found includes additional text or clauses, this should not be considered a match. -### C.3.4 Guideline: replaceable text +### Guideline: replaceable text Some licenses include text that refers to the specific copyright holder or author, yet the rest of the license is exactly the same. The intent here is to avoid the inclusion of a specific name in one part of the license resulting in a non-match where the license is otherwise an exact match to the legally substantive terms (e.g., the third clause and disclaimer in the BSD licenses, or the third, fourth, and fifth clauses of Apache-1.1). In these cases, there should be a positive license match. @@ -52,7 +52,7 @@ For example: The original replaceable text appears on the SPDX License List webpage in red text. -### C.3.5 Guideline: omittable text +### Guideline: omittable text Some licenses have text that can simply be ignored. The intent here is to avoid the inclusion of certain text that is superfluous or irrelevant in regards to the substantive license text resulting in a non-match where the license is otherwise an exact match (e.g., directions on how to apply the license or other similar exhibits). In these cases, there should be a positive license match. @@ -65,78 +65,78 @@ For example: Omittable text appears on the SPDX License List webpage in blue text. -## C.4 Whitespace +## Whitespace -### C.4.1 Purpose +### Purpose To avoid the possibility of a non-match due to different spacing of words, line breaks, or paragraphs. -### C.4.2 Guideline +### Guideline All whitespace should be treated as a single blank space. XML files do not require specific markup to implement this guideline. -## C.5 Capitalization +## Capitalization -### C.5.1 Purpose +### Purpose To avoid the possibility of a non-match due to lowercase or uppercase letters in otherwise the same words. -### C.5.2 Guideline +### Guideline All uppercase and lowercase letters should be treated as lowercase letters. XML files do not require specific markup to implement this guideline. -## C.6 Punctuation +## Punctuation -### C.6.1 Purpose +### Purpose Because punctuation can change the meaning of a sentence, punctuation needs to be included in the matching process. XML files do not require specific markup to implement this guideline, unless to indicate an exception to the guideline. -### C.6.2 Guideline: punctuation +### Guideline: punctuation Punctuation should be matched, unless otherwise stated in these guidelines or unless specific markup is added. -### C.6.3 Guideline: hyphens, dashes +### Guideline: hyphens, dashes Any hyphen, dash, en dash, em dash, or other variation should be considered equivalent. -### C.6.4 Guideline: Quotes +### Guideline: Quotes Any variation of quotations (single, double, curly, etc.) should be considered equivalent. -## C.7 Code Comment Indicators or Separators +## Code Comment Indicators or Separators -### C.7.1 Purpose +### Purpose To avoid the possibility of a non-match due to the existence or absence of code comment indicators placed within the license text, e.g., at the start of each line of text, or repetitive characters to establish a separation of text, e.g., `---`, `===`, `___`, or `***`. -### C.7.2 Guideline +### Guideline Any kind of code comment indicator or prefix which occurs at the beginning of each line in a matchable section should be ignored for matching purposes. XML files do not require specific markup to implement this guideline. -### C.7.3 Guideline +### Guideline A non-letter character repeated 3 or more times to establish a visual separation should be ignored for matching purposes. XML files do not require specific markup to implement this guideline. -## C.8 Bullets and numbering +## Bullets and numbering -### C.8.1 Purpose +### Purpose To avoid the possibility of a non-match due to the otherwise same license using bullets instead of numbers, number instead of letter, or no bullets instead of bullet, etc., for a list of clauses. -### C.8.2 Guideline +### Guideline Where a line starts with a bullet, number, letter, or some form of a list item (determined where list item is followed by a space, then the text of the sentence), ignore the list item for matching purposes. @@ -144,13 +144,13 @@ The following XML tag is used to implement this guideline: `` For example: `1.0` -## C.9 Varietal word spelling +## Varietal word spelling -### C.9.1 Purpose +### Purpose English uses different spelling for some words. By identifying the spelling variations for words found or likely to be found in licenses, we avoid the possibility of a non-match due to the same word being spelled differently. This list is not meant to be an exhaustive list of all spelling variations, but meant to capture the words most likely to be found in open source software licenses. -### C.9.2 Guideline +### Guideline The words in each line of the text file available at the [equivalent words list](https://spdx.org/licenses/equivalentwords.txt) @@ -158,13 +158,13 @@ are considered equivalent and interchangeable. XML files do not require specific markup to implement this guideline. -## C.10 Copyright symbol +## Copyright symbol -### C.10.1 Purpose +### Purpose By having a rule regarding the use of "©", "(c)", or "copyright", we avoid the possibility of a mismatch based on these variations. -### C.10.2 Guideline +### Guideline "©", "(c)", or "Copyright" should be considered equivalent and interchangeable. @@ -172,13 +172,13 @@ XML files do not require specific markup to implement this guideline. The copyright symbol is part of the copyright notice, see implementation of that guideline in [Copyright notice](#C.11). -## C.11 Copyright notice +## Copyright notice -### C.11.1 Purpose +### Purpose To avoid a license mismatch merely because the copyright notice (usually found above the actual license or exception text) is different. The copyright notice is important information to be recorded elsewhere in the SPDX document, but for the purposes of matching a license to the SPDX License List, it should be ignored because it is not part of the substantive license text. -### C.11.2 Guideline +### Guideline Ignore copyright notices. A copyright notice consists of the following elements, for example: "2012 Copyright, John Doe. All rights reserved." or "(c) 2012 John Doe." @@ -186,13 +186,13 @@ The following XML tag is used to implement this guideline: `` For example: `Copyright 2022 The Linux Foundation` -## C.12 License name or title +## License name or title -### C.12.1 Purpose +### Purpose To avoid a license mismatch merely because the name or title of the license is different than how the license is usually referred to or different than the SPDX full name. This also avoids a mismatch if the title or name of the license is simply not included. -### C.12.2 Guideline +### Guideline Ignore the license name or title for matching purposes, so long as what ignored is the title only and there is no additional substantive text added here. @@ -200,43 +200,43 @@ The following XML tag is used to implement this guideline: `` For example: `Attribution Assurance License` -## C.13 Extraneous text at the end of a license +## Extraneous text at the end of a license -### C.13.1 Purpose +### Purpose To avoid a license mismatch merely because extraneous text that appears at the end of the terms of a license is different or missing. This also avoids a mismatch if the extraneous text merely serves as a license notice example and includes a specific copyright holder's name. -### C.13.2 Guideline +### Guideline Ignore any text that occurs after the obvious end of the license and does not include substantive text of the license, for example: text that occurs after a statement such as, "END OF TERMS AND CONDITIONS," or an exhibit or appendix that includes an example or instructions on to how to apply the license to your code. Do not apply this guideline or ignore text that is comprised of additional license terms (e.g., permitted additional terms under GPL-3.0, section 7). To implement this guideline, use the `` XML element tag as described in [Guideline: omittable text](#C.3.5). -## C.14 HTTP Protocol +## HTTP Protocol -### C.14.1 Purpose +### Purpose To avoid a license mismatch due to a difference in a hyperlink protocol (e.g. http vs. https). -### C.14.2 Guideline +### Guideline HTTP:// and HTTPS:// should be considered equivalent. XML files do not require specific markup to implement this guideline. -## C.15 SPDX License list +## SPDX License list -### C.15.1 Template access +### Template access The license XML can be accessed in the license-list-data repository under the license-list-XML directory. Although the license list XML files can also be found in the [license-list-XML](https://github.com/spdx/license-list-XML) repository, users are encouraged to use the published versions in the [license-list-data](https://github.com/spdx/license-list-data) repository. The license-list-data repository is tagged by release. Only tagged released versions of the license list are considered stable. -### C.15.2 License List XML format +### License List XML format A full schema for the License List XML can be found at [SPDX License List XML Schema](https://github.com/spdx/license-list-XML/blob/master/schema/ListedLicense.xsd). -### C.15.3 Legacy Text Template format +### Legacy Text Template format Prior to the XML format, a text template was used to express variable and optional text in licenses. diff --git a/docs/annexes/pkg-url-specification.md b/docs/annexes/pkg-url-specification.md index cfd13da3df..4f9f380f65 100644 --- a/docs/annexes/pkg-url-specification.md +++ b/docs/annexes/pkg-url-specification.md @@ -1,6 +1,6 @@ -# Annex E: Package URL specification v1 (Normative) +# Package URL specification v1 (Normative) -## E.1 Introduction +## Introduction The Package URL core specification defines a versioned and formalized format, syntax, and rules used to represent and validate package URLs. @@ -17,7 +17,7 @@ Such a package URL is useful to reliably reference the same software package using a simple and expressive syntax and conventions based on familiar URLs. -## E.2 Syntax definition +## Syntax definition _purl_ stands for **package URL**. @@ -55,7 +55,7 @@ The _purl_ components are mapped to the following URL components: - _purl_ qualifiers: this maps to a URL query - _purl_ subpath: this is a URL fragment -## E.3 Character encoding +## Character encoding For clarity and simplicity a _purl_ is always an ASCII string. To ensure that there is no ambiguity when parsing a _purl_, @@ -80,7 +80,7 @@ must always percent-decode and percent-encode components and component segments as explained in the "How to produce and consume _purl_ data" section. -## E.4 Rules for each component +## Rules for each component A _purl_ string is an ASCII URL string composed of seven components. @@ -90,7 +90,7 @@ defined in the "Character encoding" section. The rules for each component are: -### E.4.1 Rules for scheme +### Rules for scheme - The scheme is a constant with the value "`pkg`" - Since a _purl_ never contains a URL Authority, its scheme must not be suffixed with double slash as in `pkg://` and should use instead `pkg:`. @@ -99,7 +99,7 @@ The rules for each component are: - The scheme is followed by a ':' separator. - For example, the two purls `pkg:gem/ruby-advisory-db-check@0.12.4` and `pkg://gem/ruby-advisory-db-check@0.12.4` are strictly equivalent. The first is in canonical form while the second is an acceptable _purl_ but is an invalid URI/URL per RFC3986. -### E.4.2 Rules for type +### Rules for type - The package type is composed only of ASCII letters and numbers, `.`, `+` and `-` (period, plus, and dash). - The type cannot start with a number. @@ -107,7 +107,7 @@ The rules for each component are: - The type must not be percent-encoded. - The type is case insensitive, with the canonical form being lowercase. -### E.4.3 Rules for namespace +### Rules for namespace - The optional namespace contains zero or more segments, separated by slash `/`. - Leading and trailing slashes `/` are not significant and should be stripped in the canonical form. They are not part of the namespace. @@ -115,20 +115,20 @@ The rules for each component are: - When percent-decoded, a segment must not contain a slash `/` and must not be empty. - A URL host or Authority must NOT be used as a namespace. Use instead a `repository_url` qualifier. Note however that for some types, the namespace may look like a host. -### E.4.4 Rules for name +### Rules for name - The name is prefixed by a slash `/` separator when the namespace is not empty. - This slash `/` is not part of the name. - A name must be a percent-encoded string. -### E.4.5 Rules for version +### Rules for version - The version is prefixed by a at-sign `@` separator when not empty. - This at-sign `@` is not part of the version. - A version must be a percent-encoded string. - A version is a plain and opaque string. Some package types use versioning conventions such as semver for NPMs or nevra conventions for RPMS. A type may define a procedure to compare and sort versions, but there is no reliable and uniform way to do such comparison consistently. -### E.4.6 Rules for qualifiers +### Rules for qualifiers - The qualifiers string is prefixed by a `?` separator when not empty. - This `?` is not part of the qualifiers. @@ -144,7 +144,7 @@ The rules for each component are: - A value must be a percent-encoded string. - The `=` separator is neither part of the key nor of the value. -### E.4.7 Rules for subpath +### Rules for subpath - The subpath string is prefixed by a `#` separator when not empty. - This `#` is not part of the subpath. @@ -154,7 +154,7 @@ The rules for each component are: - When percent-decoded, a segment must not contain a `/`, must not be any of `..` or `.`, and must not be empty. - The subpath must be interpreted as relative to the root of the package. -## E.5 Known types +## Known types There are several known _purl_ package type definitions. The current list of known types is: @@ -196,7 +196,7 @@ is maintained in the file named `PURL-TYPES.rst` in the online repository https://github.com/package-url/purl-spec. -## E.6 Known qualifiers key/value pairs +## Known qualifiers key/value pairs Qualifiers should be limited to the bare minimum for proper package identification, @@ -216,12 +216,12 @@ The following keys are valid for use in all package types: Each item in the list is in form of algorithm:hex\_value (all lowercase), such as `sha1:ad9503c3e994a4f611a4892f2e67ac82df727086`. -## E.7 How to produce and consume _purl_ data +## How to produce and consume _purl_ data The following provides rules to be followed when building or deconstructing _purl_ instances. -### E.7.1 How to build _purl_ string from its components +### How to build _purl_ string from its components Building a _purl_ ASCII string works from left to right, from type to subpath. @@ -275,7 +275,7 @@ To build a _purl_ string from its components: 1. Join the segments with `/` 1. Append this string to the _purl_ -### E.7.2 How to parse a _purl_ string to its components +### How to parse a _purl_ string to its components Parsing a _purl_ ASCII string into its components works by splitting the string on different characters. @@ -333,7 +333,7 @@ To parse a _purl_ string in its components: 1. Join segments with `/`. 1. This is the namespace. -## E.8 Examples +## Examples The following list includes some valid _purl_ examples: @@ -348,7 +348,7 @@ The following list includes some valid _purl_ examples: - `pkg:pypi/django@1.11.1` - `pkg:rpm/fedora/curl@7.50.3-1.fc25?arch=i386&distro=fedora-25` -## E.9 Original license +## Original license This specification is based on the texts published in the https://github.com/package-url/purl-spec online repository. diff --git a/docs/annexes/RDF-object-model-and-identifier-syntax.md b/docs/annexes/rdf-model.md similarity index 50% rename from docs/annexes/RDF-object-model-and-identifier-syntax.md rename to docs/annexes/rdf-model.md index d6d6d41516..d7dc6b3e9e 100644 --- a/docs/annexes/RDF-object-model-and-identifier-syntax.md +++ b/docs/annexes/rdf-model.md @@ -1,34 +1,37 @@ -# Annex B: RDF object model and identifier syntax (Normative) +# RDF model definition and diagrams (Informative) -## B.1 Introduction +## Model definition -SPDX ® Vocabulary Specification Version: 3.0.1 +The SPDX RDF ontology is expressed in RDF/OWL/SHACL format +and is published in online at +[SPDX 3.0.1 Model](https://spdx.org/rdf/3.0.1/spdx-model.ttl) -[SPDX 3.0.1 Model SHACL](https://spdx.org/rdf/3.0.1/spdx-model.ttl) + +## Diagrams ### Core and Software Profiles -[![SPDX 3.0 Core and Software Profiles diagram][fig_core_software]][fig_core_software] +[![Core and Software Profiles diagram][fig_core_software]][fig_core_software] -### AI Profile +### Licensing Profile -[![SPDX 3.0 AI Profile diagram][fig_ai]][fig_ai] +[![Licensing Profile diagram][fig_licensing]][fig_licensing] -### Build Profile +### Security Profile -[![SPDX 3.0 Build Profile diagram][fig_build]][fig_build] +[![Security Profile diagram][fig_security]][fig_security] ### Dataset Profile -[![SPDX 3.0 Dataset Profile diagram][fig_dataset]][fig_dataset] +[![Dataset Profile diagram][fig_dataset]][fig_dataset] -### Licensing Profile +### AI Profile -[![SPDX 3.0 Licensing Profile diagram][fig_licensing]][fig_licensing] +[![AI Profile diagram][fig_ai]][fig_ai] -### Security Profile +### Build Profile -[![SPDX 3.0 Security Profile diagram][fig_security]][fig_security] +[![Build Profile diagram][fig_build]][fig_build] [fig_core_software]: ../images/model-core-software.png "SPDX 3.0 Core and Software Profiles diagram" [fig_ai]: ../images/model-ai.png "SPDX 3.0 AI Profile diagram" diff --git a/docs/annexes/using-SPDX-short-identifiers-in-source-files.md b/docs/annexes/using-SPDX-short-identifiers-in-source-files.md deleted file mode 100644 index d358063ffc..0000000000 --- a/docs/annexes/using-SPDX-short-identifiers-in-source-files.md +++ /dev/null @@ -1,73 +0,0 @@ -# Annex E: Using SPDX license list short identifiers in source files (Informative) - -TODO: update for SPDXv3 - -## E.1 Introduction - -Identifying the license for open source software is critical for both reporting purposes and license compliance. However, determining the license can sometimes be difficult due to a lack of information or ambiguous information. Even when licensing information is present, a lack of consistent notation can make automating the task of license detection very difficult, thus requiring vast amounts of human effort. - -[Short identifiers](https://spdx.org/licenses/) from the SPDX License List can be used to indicate license info at the file level. The advantages of doing this are numerous but include: - -* It is precise. -* It is concise. -* It is language neutral. -* It is easy and more reliable to machine process. -* Leads to code that is easier to reuse. -* The license information travels with the file (as sometimes not entire projects are used or license files are removed). -* It is a standard and can be universal. There is no need for variation. -* An SPDX short identifier is immutable. -* Easy look-ups and cross-references to the SPDX License List website. - -If using SPDX short identifiers in individual files, it is recommended to reproduce the full license in the projects LICENSE file and indicate that SPDX short identifiers are being used to refer to it. For links to projects illustrating these scenarios, see [https://spdx.dev/ids-where](https://spdx.dev/ids-where). - -## E.2 Format for SPDX-License-Identifier - -The SPDX-License-Identifier tag declares the license the file is under and should be placed at or near the top of the file in a comment. - -The SPDX License Identifier syntax may consist of a single license (represented by a short identifier from the [SPDX license list](https://spdx.org/licenses/)) or a compound set of licenses (represented by joining together multiple licenses using the license expression syntax). - -The tag should appear on its own line in the source file, generally as part of a comment. - -```text -SPDX-License-Identifier: -``` - -## E.3 Representing single license - -A single license is represented by using the short identifier from [SPDX license list](https://spdx.org/licenses/), optionally with a unary "+" operator following it to indicate "or later" versions may be applicable. - -Examples: - -```text -SPDX-License-Identifier: CDDL-1.0+ -SPDX-License-Identifier: MIT -``` - -## E.4 Representing multiple licenses - -Multiple licenses can be represented using an SPDX license expression as defined in Annex [D](SPDX-license-expressions.md). A set of licenses may optionally be enclosed in parentheses, but are not required to be enclosed. As further described there: - -1. When there is a choice between licenses ("disjunctive license"), they should be separated with "OR". If presented with a choice between two or more licenses, use the disjunctive binary "OR" operator to construct a new license expression. -2. Similarly when multiple licenses need to be simultaneously applied ("conjunctive license"), they should be separated with "AND". If required to simultaneously comply with two or more licenses, use the conjunctive binary "AND" operator to construct a new license expression. -3. In some cases, a set of license terms apply except under special circumstances, in this case, use the "WITH" operator followed by one of the [recognized exception identifiers](https://spdx.org/licenses/exceptions-index.html). -4. The expression MUST be on a single line, and MUST NOT include a line break in the middle of the expression. - -Examples: - -```text -SPDX-License-Identifier: GPL-2.0-only OR MIT -SPDX-License-Identifier: LGPL-2.1-only AND BSD-2-Clause -SPDX-License-Identifier: GPL-2.0-or-later WITH Bison-exception-2.2 -``` - -Please see Annex [D](SPDX-license-expressions.md) for more examples and details of the license expression specific syntax. - -If you can’t express the license(s) as an expression using identifiers from the SPDX list, it is probably best to just put the text of your license header in the file (if there is a standard header), or refer to a neutral site URL where the text can be found. To request a license be added to the SPDX License List, please follow the process described here: [https://github.com/spdx/license-list-XML/blob/master/CONTRIBUTING.md](https://github.com/spdx/license-list-XML/blob/master/CONTRIBUTING.md). - -Alternatively, you can use a `LicenseRef-` custom license identifier to refer to a license that is not on the SPDX License List, such as the following: - -```text -SPDX-License-Identifier: LicenseRef-my-special-license -``` - -The `LicenseRef-` format is defined in Annex [D](SPDX-license-expressions.md). When using a custom `LicenseRef-` identifier, you will also need to provide a way for others to determine what license text corresponds to it. [Version 3.0 of the REUSE Software Specification](https://reuse.software/spec/) provides a standardized format that can optionally be used for providing the corresponding license text for these identifiers. diff --git a/docs/annexes/using-SPDX-to-comply-with-industry-guidance.md b/docs/annexes/using-SPDX-to-comply-with-industry-guidance.md deleted file mode 100644 index f45d6d23b3..0000000000 --- a/docs/annexes/using-SPDX-to-comply-with-industry-guidance.md +++ /dev/null @@ -1,61 +0,0 @@ -# Annex F: Using SPDX to comply with Norms, Standards and Regulation (Informative) - -## F.1 Satisfying NTIA Minimum Elements for an SBOM using SPDX / US Executive Order 14028 - -US Executive Order 14028 in conjunction with the National Telecommunications -and Information Administration (NTIA) outlined minimum elements for an SBOM. -The minimum elements are detailed in -[NTIA's Framing Software Component Transparency: Establishing a Common Software Bill of Maternials](https://www.ntia.gov/files/ntia/publications/framingsbom_20191112.pdf) -and -[The Minimum Elements for a SBOM](https://www.ntia.doc.gov/files/ntia/publications/sbom_minimum_elements_report.pdf) -documents and summarized below: - -| SBOM Minimum Field | Description | -| ----------- | :----------- | -| Author Name | Author of the SBOM entry (this may not always be the supplier). | -| Supplier Name | Name or identity of the supplier of the component in the SBOM entry. | -| Component Name | Designation assigned to a unit of software defined by the original supplier. | -| Version String | Version used to identify a component. | -| Component Hash | A cryptographic hash to uniquely identify a component. | -| Unique Identifier | A unique identifier to help identify components or serve as a look-up key for relevant databases. | -| Relationship | Characterizing the relationship that an upstream component X is included in software Y. | -| Timestamp | Record of the date and time of the SBOM data assembly. | - -The SPDX Specification contains fields able to address each of the NTIA minimum required data fields. - -| NTIA SBOM Minimum Field | Satisfying SPDX field model location | -| ----------- | :----------- | -| Author Name | [Core/Classes/CreationInfo.createdBy](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/CreationInfo/) | -| Supplier Name | [Core/Classes/Artifact.suppliedBy](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Artifact/) | -| Component Name | [Software/Classes/Package.name](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/Package/) inherited from [Core/Classes/Element.name](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/) | -| Version String | [Software/Classes/Package.packageVersion](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/Package/) | -| Component Hash | [Core/Classes/Element.verifiedUsing](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/) | -| Unique Identifier | [Software/Classes/SoftwareArtifact.contentIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/SoftwareArtifact/) for SPDX Software Artifacts or [Software/Classes/Package.packageUrl](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/Package/) if the packageUrl is considered to be unique,
or [Core/Classes/Element.externalIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/) for resources outside the scope of SPDX-3.0 content
| -| Relationship | [Core/Classes/Relationship](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Relationship/) | -| Timestamp | [Core/Classes/CreationInfo.created](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/CreationInfo/) | - -## F.2 BSI TR-03183 - Technical Guideline Cyber Resilience Requirements for Manufacturers and Products - -The German BSI is actively propagating its technical guideline in preparation -for adopting and detailing the requirements of the -[EU Cyber Resilience Act](https://www.europarl.europa.eu/doceo/document/TA-9-2024-0130_EN.html) -becoming effective in 2027. - -The guideline can be regarded as German equivalent of the US Executive Order -14028. Nevertheless, BSI is exploring various options and recommendations to -further detail the content of SBOMs. - -Important elements of the guideline in the context of SPDX: - -- The guideline references SPDX as one of the exchange formats for SBOMs. -- It defines levels of details as well as mandatory and optional data fields. -- The guideline scopes the content (dependency relationships) of an SBOM - (top-level, n-level, transitive, delivery item, complete). -- Different types of SBOMs (design, source, build, analysed, deployed, runtime) - are defined. - -The guideline (available in version 1.1) is currently being revised by the BSI. -Draft versions of the future 2.0 document are circulated by the BSI to collect -review comments. - -See [BSI Technical Guideline TR-03183](https://www.bsi.bund.de/SharedDocs/Downloads/EN/BSI/Publications/TechGuidelines/TR03183/BSI-TR-03183-2.html). diff --git a/docs/bibliography.md b/docs/bibliography.md deleted file mode 100644 index 91a067dbd1..0000000000 --- a/docs/bibliography.md +++ /dev/null @@ -1,7 +0,0 @@ -# Bibliography - -The following documents are useful references for implementers and users of this document: - -[1] *Software Package Data Exchange (SPDX®) Specification Version 1.0* and 1.1, 1.2, 2.0, 2.1, 2.2, and 2.3; SPDX.dev, - -[2] *Open Source Initiative (OSI)*; From bcade383d94bc2a7fb82649122c780ce26f53674 Mon Sep 17 00:00:00 2001 From: Alexios Zavras Date: Sun, 11 Aug 2024 18:00:07 +0200 Subject: [PATCH 3/4] Updates mkdocs configuration with chapters and annexes Signed-off-by: Alexios Zavras --- mkdocs.yml | 29 ++++++++++++----------------- 1 file changed, 12 insertions(+), 17 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index b5e6703404..838f0937cf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -34,27 +34,22 @@ validation: nav: - 'Copyright': index.md - 'Introduction': introduction.md -- 'Scope': scope.md -- 'Normative references': normative-references.md -- 'Terms and definitions': terms-and-definitions.md -- 'Model and serializations': serializations.md -- 'Bibliography': bibliography.md +- '1. Scope': scope.md +- '2. References': references.md +- '3. Symbols': symbols.md +- '4. Conformance': conformance.md +- '5. Model and serializations': serializations.md - model: # [MODEL_PLACEHOLDER], to be replaced by content from mkdocs-files.yml - annexes: - - 'Diffs from Previous Editions': annexes/diffs-from-previous-editions.md - - 'Getting started with SPDX 3': annexes/getting-started.md - - 'RDF Object Model and Identifier Syntax': annexes/RDF-object-model-and-identifier-syntax.md - - 'SPDX License Expressions': annexes/SPDX-license-expressions.md - - 'SPDX license list matching guidelines': annexes/license-matching-guidelines-and-templates.md - - 'Using SPDX short identifiers in Source Files': annexes/using-SPDX-short-identifiers-in-source-files.md - - 'Using SPDX to comply with norms, standards and regulation': annexes/using-SPDX-to-comply-with-industry-guidance.md - - 'Including Security Information in SPDX': annexes/including-security-information-in-SPDX.md - - 'SPDX Lite': annexes/SPDX-Lite.md - - 'Cross-referencing in SPDX 3': annexes/cross-reference.md - - 'Package URL specification': annexes/pkg-url-specification.md + - 'A. Changes from the previous standard': annexes/diffs-from-previous-iso.md + - 'B. RDF model definition and diagrams': annexes/rdf-model.md + - 'C. SPDX license expressions': annexes/SPDX-license-expressions.md + - 'D. SPDX license list matching guidelines': annexes/license-matching-guidelines-and-templates.md + - 'E. SPDX Lite': annexes/SPDX-Lite.md + - 'F. Package URL specification': annexes/pkg-url-specification.md - licenses: - - 'Creative Commons Attribution License 3.0 Unported': licenses/CC-BY-3.0.md - 'Community Specification License 1.0': licenses/Community-Spec-1.0.md + - 'Creative Commons Attribution License 3.0 Unported': licenses/CC-BY-3.0.md draft_docs: | # for preview with `mkdocs serve`, but excluded from `mkdocs build` omg-preface.md iso-foreword.md From d60476eec3a3b43c35b8918a22e83b9916f3e532 Mon Sep 17 00:00:00 2001 From: Gary O'Neall Date: Sun, 11 Aug 2024 14:02:10 -0700 Subject: [PATCH 4/4] Remove the TODO Co-authored-by: Kate Stewart <13152682+kestewart@users.noreply.github.com> Signed-off-by: Gary O'Neall --- docs/annexes/changes-from-previous-iso.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/annexes/changes-from-previous-iso.md b/docs/annexes/changes-from-previous-iso.md index 33d7589a9e..8b44b99773 100644 --- a/docs/annexes/changes-from-previous-iso.md +++ b/docs/annexes/changes-from-previous-iso.md @@ -11,5 +11,4 @@ in 2021. The present chapter outlines the changes that the current version introduces related to that previous edition. -## TODO: Kate to fill in ...