From a2b13d1bd6fef1ecf9113e22cd94db6c959d08ac Mon Sep 17 00:00:00 2001 From: Jan Kowalleck Date: Tue, 6 Feb 2024 16:54:51 +0100 Subject: [PATCH 1/6] make metadata field descibtion more clear. fix #345 #273 Signed-off-by: Jan Kowalleck --- schema/bom-1.6.proto | 12 ++++++------ schema/bom-1.6.schema.json | 19 ++++++++++--------- schema/bom-1.6.xsd | 33 ++++++++++++++++++++++++--------- 3 files changed, 40 insertions(+), 24 deletions(-) diff --git a/schema/bom-1.6.proto b/schema/bom-1.6.proto index 89991875..42c0cf0c 100644 --- a/schema/bom-1.6.proto +++ b/schema/bom-1.6.proto @@ -436,19 +436,19 @@ enum LicensingTypeEnum { } message Metadata { - // The date and time (timestamp) when the document was created. + // The date and time (timestamp) when the CycloneDX document was created. optional google.protobuf.Timestamp timestamp = 1; - // The tool(s) used in the creation of the BOM. + // The tool(s) used in the creation of the Cyclonedx document. optional Tool tools = 2; - // The person(s) who created the BOM. Authors are common in BOMs created through manual processes. BOMs created through automated means may not have authors. + // The person(s) who created the CycloneDX document. Authors are common in documents created through manual processes. Documents created through automated means may not have authors. This may be different from the author(s) of the component that the the CycloneDX document describes. repeated OrganizationalContact authors = 3; // The component that the BOM describes. optional Component component = 4; - // The organization that manufactured the component that the BOM describes. + // The organization that manufactured the CycloneDX document. This may be different from the manufacurer of the component that the the CycloneDX document describes. optional OrganizationalEntity manufacture = 5; - // The organization that supplied the component that the BOM describes. The supplier may often be the manufacture, but may also be a distributor or repackager. + // The organization that supplied the CycloneDX document. The supplier may often be the manufacture, but may also be a distributor or repackager. This may be different from the supplier of the component that the the CycloneDX document describes. optional OrganizationalEntity supplier = 6; - // The license information for the BOM document + // The license information for the CycloneDX document. This may be different from the license(s) of the component that the the CycloneDX document describes. optional LicenseChoice licenses = 7; // Specifies optional, custom, properties repeated Property properties = 8; diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index 695b1d2d..a4d56406 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -573,7 +573,7 @@ "type": "string", "format": "date-time", "title": "Timestamp", - "description": "The date and time (timestamp) when the BOM was created." + "description": "The date and time (timestamp) when the CycloneDX document was created." }, "lifecycles": { "type": "array", @@ -633,13 +633,13 @@ } ] } - }, + }, "tools": { "oneOf": [ { "type": "object", "title": "Creation Tools", - "description": "The tool(s) used in the creation of the BOM.", + "description": "The tool(s) used in the creation of the CycloneDX document.", "additionalProperties": false, "properties": { "components": { @@ -661,7 +661,7 @@ { "type": "array", "title": "Creation Tools (legacy)", - "description": "[Deprecated] The tool(s) used in the creation of the BOM.", + "description": "[Deprecated] The tool(s) used in the creation of the CycloneDX document.", "items": {"$ref": "#/definitions/tool"} } ] @@ -669,26 +669,27 @@ "authors" :{ "type": "array", "title": "Authors", - "description": "The person(s) who created the BOM. Authors are common in BOMs created through manual processes. BOMs created through automated means may not have authors.", + "description": "The person(s) who created the CycloneDX document.\nAuthors are common in documents created through manual processes. Documents created through automated means may not have authors.\nThis may be different from the author(s) of the component that the the CycloneDX document describes.", "items": {"$ref": "#/definitions/organizationalContact"} }, "component": { "title": "Component", - "description": "The component that the BOM describes.", + "description": "The component that the the CycloneDX document describes.", "$ref": "#/definitions/component" }, "manufacture": { "title": "Manufacture", - "description": "The organization that manufactured the component that the BOM describes.", + "description": "The organization that manufactured the CycloneDX document.\nThis may be different from the manufacturer of the component that the the CycloneDX document describes.", "$ref": "#/definitions/organizationalEntity" }, "supplier": { "title": "Supplier", - "description": " The organization that supplied the component that the BOM describes. The supplier may often be the manufacturer, but may also be a distributor or repackager.", + "description": " The organization that supplied the CycloneDX document. The supplier may often be the manufacturer, but may also be a distributor or repackager.\nThis may be different from the supplier of the component that the the CycloneDX document describes.", "$ref": "#/definitions/organizationalEntity" }, "licenses": { - "title": "BOM License(s)", + "title": "Document's License(s)", + "description": "The license(s) to apply to the CycloneDX document.\nThis may be different from the license(s) of the component that the the CycloneDX document describes.", "$ref": "#/definitions/licenseChoice" }, "properties": { diff --git a/schema/bom-1.6.xsd b/schema/bom-1.6.xsd index c3c9b230..c156f642 100644 --- a/schema/bom-1.6.xsd +++ b/schema/bom-1.6.xsd @@ -123,7 +123,7 @@ limitations under the License. - The date and time (timestamp) when the BOM was created. + The date and time (timestamp) when the CycloneDX document was created. @@ -170,7 +170,7 @@ limitations under the License. - The tool(s) used in the creation of the BOM. + The tool(s) used in the creation of the CycloneDX document. @@ -198,8 +198,11 @@ limitations under the License. - The person(s) who created the BOM. Authors are common in BOMs created through - manual processes. BOMs created through automated means may not have authors. + + The person(s) who created the CycloneDX document. + Authors are common in documents created through manual processes. Documents created through automated means may not have authors. + This may be different from the author(s) of the component that the the CycloneDX document describes. + @@ -209,21 +212,33 @@ limitations under the License. - The component that the BOM describes. + The component that the the CycloneDX document describes. - The organization that manufactured the component that the BOM describes. + + The organization that manufactured the CycloneDX document. + This may be different from the manufacturer of the component that the the CycloneDX document describes. + - The organization that supplied the component that the BOM describes. The - supplier may often be the manufacturer, but may also be a distributor or repackager. + + The organization that supplied the CycloneDX document. The supplier may often be the manufacturer, but may also be a distributor or repackager. + This may be different from the supplier of the component that the the CycloneDX document describes. + + + + + + + The license(s) to applies to the CycloneDX document. + This may be different from the license(s) of the component that the the CycloneDX document describes. + - Provides the ability to document properties in a name/value store. From 6d31f50694cf336616ac34b54a1ce857bfd11277 Mon Sep 17 00:00:00 2001 From: Jan Kowalleck Date: Wed, 7 Feb 2024 19:57:21 +0100 Subject: [PATCH 2/6] fixed a typo Signed-off-by: Jan Kowalleck --- schema/bom-1.6.proto | 8 ++++---- schema/bom-1.6.schema.json | 10 +++++----- schema/bom-1.6.xsd | 10 +++++----- 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/schema/bom-1.6.proto b/schema/bom-1.6.proto index 42c0cf0c..0f5b65cd 100644 --- a/schema/bom-1.6.proto +++ b/schema/bom-1.6.proto @@ -440,15 +440,15 @@ message Metadata { optional google.protobuf.Timestamp timestamp = 1; // The tool(s) used in the creation of the Cyclonedx document. optional Tool tools = 2; - // The person(s) who created the CycloneDX document. Authors are common in documents created through manual processes. Documents created through automated means may not have authors. This may be different from the author(s) of the component that the the CycloneDX document describes. + // The person(s) who created the CycloneDX document. Authors are common in documents created through manual processes. Documents created through automated means may not have authors. This may be different from the author(s) of the component that the CycloneDX document describes. repeated OrganizationalContact authors = 3; // The component that the BOM describes. optional Component component = 4; - // The organization that manufactured the CycloneDX document. This may be different from the manufacurer of the component that the the CycloneDX document describes. + // The organization that manufactured the CycloneDX document. This may be different from the manufacurer of the component that the CycloneDX document describes. optional OrganizationalEntity manufacture = 5; - // The organization that supplied the CycloneDX document. The supplier may often be the manufacture, but may also be a distributor or repackager. This may be different from the supplier of the component that the the CycloneDX document describes. + // The organization that supplied the CycloneDX document. The supplier may often be the manufacture, but may also be a distributor or repackager. This may be different from the supplier of the component that the CycloneDX document describes. optional OrganizationalEntity supplier = 6; - // The license information for the CycloneDX document. This may be different from the license(s) of the component that the the CycloneDX document describes. + // The license information for the CycloneDX document. This may be different from the license(s) of the component that the CycloneDX document describes. optional LicenseChoice licenses = 7; // Specifies optional, custom, properties repeated Property properties = 8; diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index a4d56406..638cd3cb 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -669,27 +669,27 @@ "authors" :{ "type": "array", "title": "Authors", - "description": "The person(s) who created the CycloneDX document.\nAuthors are common in documents created through manual processes. Documents created through automated means may not have authors.\nThis may be different from the author(s) of the component that the the CycloneDX document describes.", + "description": "The person(s) who created the CycloneDX document.\nAuthors are common in documents created through manual processes. Documents created through automated means may not have authors.\nThis may be different from the author(s) of the component that the CycloneDX document describes.", "items": {"$ref": "#/definitions/organizationalContact"} }, "component": { "title": "Component", - "description": "The component that the the CycloneDX document describes.", + "description": "The component that the CycloneDX document describes.", "$ref": "#/definitions/component" }, "manufacture": { "title": "Manufacture", - "description": "The organization that manufactured the CycloneDX document.\nThis may be different from the manufacturer of the component that the the CycloneDX document describes.", + "description": "The organization that manufactured the CycloneDX document.\nThis may be different from the manufacturer of the component that the CycloneDX document describes.", "$ref": "#/definitions/organizationalEntity" }, "supplier": { "title": "Supplier", - "description": " The organization that supplied the CycloneDX document. The supplier may often be the manufacturer, but may also be a distributor or repackager.\nThis may be different from the supplier of the component that the the CycloneDX document describes.", + "description": " The organization that supplied the CycloneDX document. The supplier may often be the manufacturer, but may also be a distributor or repackager.\nThis may be different from the supplier of the component that the CycloneDX document describes.", "$ref": "#/definitions/organizationalEntity" }, "licenses": { "title": "Document's License(s)", - "description": "The license(s) to apply to the CycloneDX document.\nThis may be different from the license(s) of the component that the the CycloneDX document describes.", + "description": "The license(s) to apply to the CycloneDX document.\nThis may be different from the license(s) of the component that the CycloneDX document describes.", "$ref": "#/definitions/licenseChoice" }, "properties": { diff --git a/schema/bom-1.6.xsd b/schema/bom-1.6.xsd index c156f642..007675ae 100644 --- a/schema/bom-1.6.xsd +++ b/schema/bom-1.6.xsd @@ -201,7 +201,7 @@ limitations under the License. The person(s) who created the CycloneDX document. Authors are common in documents created through manual processes. Documents created through automated means may not have authors. - This may be different from the author(s) of the component that the the CycloneDX document describes. + This may be different from the author(s) of the component that the CycloneDX document describes. @@ -212,14 +212,14 @@ limitations under the License. - The component that the the CycloneDX document describes. + The component that the CycloneDX document describes. The organization that manufactured the CycloneDX document. - This may be different from the manufacturer of the component that the the CycloneDX document describes. + This may be different from the manufacturer of the component that the CycloneDX document describes. @@ -227,7 +227,7 @@ limitations under the License. The organization that supplied the CycloneDX document. The supplier may often be the manufacturer, but may also be a distributor or repackager. - This may be different from the supplier of the component that the the CycloneDX document describes. + This may be different from the supplier of the component that the CycloneDX document describes. @@ -235,7 +235,7 @@ limitations under the License. The license(s) to applies to the CycloneDX document. - This may be different from the license(s) of the component that the the CycloneDX document describes. + This may be different from the license(s) of the component that the CycloneDX document describes. From 250dd20ad1e1c18c83afa667682ee72cd038c7fe Mon Sep 17 00:00:00 2001 From: Jan Kowalleck Date: Thu, 8 Feb 2024 12:41:45 +0100 Subject: [PATCH 3/6] point to mispelled "manufacture"/"manufacturer" Signed-off-by: Jan Kowalleck --- schema/bom-1.6.proto | 2 +- schema/bom-1.6.schema.json | 4 ++-- schema/bom-1.6.xsd | 3 ++- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/schema/bom-1.6.proto b/schema/bom-1.6.proto index 0f5b65cd..8208c646 100644 --- a/schema/bom-1.6.proto +++ b/schema/bom-1.6.proto @@ -446,7 +446,7 @@ message Metadata { optional Component component = 4; // The organization that manufactured the CycloneDX document. This may be different from the manufacurer of the component that the CycloneDX document describes. optional OrganizationalEntity manufacture = 5; - // The organization that supplied the CycloneDX document. The supplier may often be the manufacture, but may also be a distributor or repackager. This may be different from the supplier of the component that the CycloneDX document describes. + // The organization that supplied the CycloneDX document (the "manufacturer", although the field is misspelled). The supplier may often be the manufacture, but may also be a distributor or repackager. This may be different from the supplier of the component that the CycloneDX document describes. optional OrganizationalEntity supplier = 6; // The license information for the CycloneDX document. This may be different from the license(s) of the component that the CycloneDX document describes. optional LicenseChoice licenses = 7; diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json index 638cd3cb..31db5bb7 100644 --- a/schema/bom-1.6.schema.json +++ b/schema/bom-1.6.schema.json @@ -678,8 +678,8 @@ "$ref": "#/definitions/component" }, "manufacture": { - "title": "Manufacture", - "description": "The organization that manufactured the CycloneDX document.\nThis may be different from the manufacturer of the component that the CycloneDX document describes.", + "title": "Manufacturer", + "description": "The organization that manufactured the CycloneDX document (the \"manufacturer\", although the property is misspelled).\nThis may be different from the manufacturer of the component that the CycloneDX document describes.", "$ref": "#/definitions/organizationalEntity" }, "supplier": { diff --git a/schema/bom-1.6.xsd b/schema/bom-1.6.xsd index 007675ae..3d7f50ae 100644 --- a/schema/bom-1.6.xsd +++ b/schema/bom-1.6.xsd @@ -218,7 +218,8 @@ limitations under the License. - The organization that manufactured the CycloneDX document. + The organization that manufactured the CycloneDX document (the "manufacturer", although the + element is misspelled). This may be different from the manufacturer of the component that the CycloneDX document describes. From 562416916fa4db0cdf9148ea99b7f567d702b940 Mon Sep 17 00:00:00 2001 From: Jan Kowalleck Date: Thu, 8 Feb 2024 13:55:06 +0100 Subject: [PATCH 4/6] XML escape quot Signed-off-by: Jan Kowalleck --- schema/bom-1.6.xsd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schema/bom-1.6.xsd b/schema/bom-1.6.xsd index 3d7f50ae..c4764ef8 100644 --- a/schema/bom-1.6.xsd +++ b/schema/bom-1.6.xsd @@ -218,7 +218,7 @@ limitations under the License. - The organization that manufactured the CycloneDX document (the "manufacturer", although the + The organization that manufactured the CycloneDX document (the "manufacturer", although the element is misspelled). This may be different from the manufacturer of the component that the CycloneDX document describes. From 771133f9294d36172af74bd096a167feec4f47c2 Mon Sep 17 00:00:00 2001 From: Jan Kowalleck Date: Thu, 8 Feb 2024 14:58:12 +0100 Subject: [PATCH 5/6] docs Signed-off-by: Jan Kowalleck --- schema/bom-1.6.proto | 2 +- schema/bom-1.6.xsd | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/schema/bom-1.6.proto b/schema/bom-1.6.proto index 8208c646..9a3cd733 100644 --- a/schema/bom-1.6.proto +++ b/schema/bom-1.6.proto @@ -444,7 +444,7 @@ message Metadata { repeated OrganizationalContact authors = 3; // The component that the BOM describes. optional Component component = 4; - // The organization that manufactured the CycloneDX document. This may be different from the manufacurer of the component that the CycloneDX document describes. + // The organization that manufactured the CycloneDX document (the "manufacturer", although the field is misspelled). This may be different from the manufacurer of the component that the CycloneDX document describes. optional OrganizationalEntity manufacture = 5; // The organization that supplied the CycloneDX document (the "manufacturer", although the field is misspelled). The supplier may often be the manufacture, but may also be a distributor or repackager. This may be different from the supplier of the component that the CycloneDX document describes. optional OrganizationalEntity supplier = 6; diff --git a/schema/bom-1.6.xsd b/schema/bom-1.6.xsd index c4764ef8..fea624d8 100644 --- a/schema/bom-1.6.xsd +++ b/schema/bom-1.6.xsd @@ -218,8 +218,7 @@ limitations under the License. - The organization that manufactured the CycloneDX document (the "manufacturer", although the - element is misspelled). + The organization that manufactured the CycloneDX document (the "manufacturer", although the element is misspelled). This may be different from the manufacturer of the component that the CycloneDX document describes. From a7f474bee16956639520884df88300ac02fbaec9 Mon Sep 17 00:00:00 2001 From: Jan Kowalleck Date: Thu, 8 Feb 2024 14:59:16 +0100 Subject: [PATCH 6/6] docs Signed-off-by: Jan Kowalleck --- schema/bom-1.6.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schema/bom-1.6.proto b/schema/bom-1.6.proto index 9a3cd733..6947085f 100644 --- a/schema/bom-1.6.proto +++ b/schema/bom-1.6.proto @@ -446,7 +446,7 @@ message Metadata { optional Component component = 4; // The organization that manufactured the CycloneDX document (the "manufacturer", although the field is misspelled). This may be different from the manufacurer of the component that the CycloneDX document describes. optional OrganizationalEntity manufacture = 5; - // The organization that supplied the CycloneDX document (the "manufacturer", although the field is misspelled). The supplier may often be the manufacture, but may also be a distributor or repackager. This may be different from the supplier of the component that the CycloneDX document describes. + // The organization that supplied the CycloneDX document. The supplier may often be the manufacture, but may also be a distributor or repackager. This may be different from the supplier of the component that the CycloneDX document describes. optional OrganizationalEntity supplier = 6; // The license information for the CycloneDX document. This may be different from the license(s) of the component that the CycloneDX document describes. optional LicenseChoice licenses = 7;