feat: decouple metadata from its component (#379)

The following changes were made with the intent to not introduce breaking changes, neither syntactic nor semantic(!) ## Changes - add `component.manufacturer` as "OrganizationalEntity" -- fixes #346 - add `component.authors` as list of "OrganizationalContact" -- fixes #335 - deprecate `component.author` in favour of `component.authors` and `component.manufacturer` - reason: value was described to be a string that could represent person(s) or organization(s). So let's introduce dedicated fields for both of these: Organizations are represented by the new `@.manufacturer` & persons are represented by the new `@.authors`. - add `metatada.manufaturer` as "OrganizationalEntity" -- fixes #57 - deprecate `metatada.manufature` in favour of `metadata.component.manufacturer` -- fixes #346 ---- ## TODO - [x] update JSON schema - [x] update XSD - [x] update protobuff schema - [x] add examples and test resources ## Follow up tasks - [ ] update use cases on the Website - [ ] update SBOM guide - [ ] create a BC task for 2.0: remove deprecated `metadata.manufacture` - [ ] create a BC task for 2.0: remove deprecated `component.author`
CycloneDX · Feb 22, 2024 · 2734b3f · 2734b3f
2 parents d7753f7 + f4049d8
commit 2734b3f
Show file tree

Hide file tree

Showing 12 changed files with 201 additions and 32 deletions.
diff --git a/schema/bom-1.6.proto b/schema/bom-1.6.proto
@@ -97,8 +97,8 @@ message Component {
   optional string bom_ref = 3;
   // The organization that supplied the component. The supplier may often be the manufacture, but may also be a distributor or repackager.
   optional OrganizationalEntity supplier = 4;
-  // The person(s) or organization(s) that authored the component
-  optional string author = 5;
+  // DEPRECATED - DO NOT USE - This will be removed in a future version - Use `.authors` or `.manufacturer` instead. The person(s) or organization(s) that authored the component
+  optional string author = 5 [deprecated = true];
   // The person(s) or organization(s) that published the component
   optional string publisher = 6;
   // The grouping name or identifier. This will often be a shortened, single name of the company or project that produced the component, or the source package or domain name. Whitespace and special characters should be avoided. Examples include: apache, org.apache.commons, and apache.org.
@@ -141,8 +141,12 @@ message Component {
   optional ComponentData data = 26;
   // Cryptographic assets have properties that uniquely define them and that make them actionable for further reasoning. As an example, it makes a difference if one knows the algorithm family (e.g. AES) or the specific variant or instantiation (e.g. AES-128-GCM). This is because the security level and the algorithm primitive (authenticated encryption) is only defined by the definition of the algorithm variant. The presence of a weak cryptographic algorithm like SHA1 vs. HMAC-SHA1 also makes a difference.
   optional CryptoProperties cryptoProperties = 27;
+  // The organization that created the component. Manufacturer is common in components created through automated processes. Components created through manual means may have `.authors` instead.
+  optional OrganizationalEntity manufacturer = 28;
+  // The person(s) who created the component. Authors are common in components created through manual processes. Components created through automated means may have `.manufacturer` instead.
+  repeated OrganizationalContact authors = 29;
   // Textual strings that aid in discovery, search, and retrieval of the associated object. Tags often serve as a way to group or categorize similar or related objects by various attributes. Examples include "json-parser", "object-persistence", "text-to-image", "translation", and "object-detection".
-  repeated string tags = 28;
+  repeated string tags = 30;
 }
 
 // Specifies the data flow.
@@ -442,12 +446,12 @@ message Metadata {
   optional google.protobuf.Timestamp timestamp = 1;
   // The tool(s) used in the creation of the BOM.
   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 BOM. Authors are common in BOMs created through manual processes. BOMs created through automated means may have '.manufacturer' instead.
   repeated OrganizationalContact authors = 3;
   // The component that the BOM describes.
   optional Component component = 4;
-  // The organization that manufactured the component that the BOM describes.
-  optional OrganizationalEntity manufacture = 5;
+  // DEPRECATED - DO NOT USE - This will be removed in a future version - Use the `.component.manufacturer` instead. The organization that manufactured the component that the BOM describes.
+  optional OrganizationalEntity manufacture = 5 [deprecated = true];
   // 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.
   optional OrganizationalEntity supplier = 6;
   // The license information for the BOM document. This may be different from the license(s) of the component that the BOM describes.
@@ -456,6 +460,8 @@ message Metadata {
   repeated Property properties = 8;
   // The product lifecycle(s) that this BOM represents.
   repeated Lifecycles lifecycles = 9;
+  // The organization that created the BOM. Manufacturer is common in BOMs created through automated processes. BOMs created through manual means may have '.authors' instead.
+  optional OrganizationalEntity manufacturer = 10;
 }
 
 message Lifecycles {

diff --git a/schema/bom-1.6.schema.json b/schema/bom-1.6.schema.json
@@ -668,10 +668,15 @@
             }
           ]
         },
-        "authors" :{
+        "manufacturer": {
+          "title": "BOM Manufacturer",
+          "description": "The organization that created the BOM.\nManufacturer is common in BOMs created through automated processes. BOMs created through manual means may have '@.authors' instead.",
+          "$ref": "#/definitions/organizationalEntity"
+        },
+        "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.",
+          "title": "BOM Authors",
+          "description": "The person(s) who created the BOM.\nAuthors are common in BOMs created through manual processes. BOMs created through automated means may have '@.manufacturer' instead.",
           "items": {"$ref": "#/definitions/organizationalContact"}
         },
         "component": {
@@ -680,8 +685,9 @@
           "$ref": "#/definitions/component"
         },
         "manufacture": {
-          "title": "Manufacture",
-          "description": "The organization that manufactured the component that the BOM describes.",
+          "deprecated": true,
+          "title": "Component Manufacture (legacy)",
+          "description": "[Deprecated] - DO NOT USE. This will be removed in a future version. Use the `@.component.manufacturer` instead.\nThe organization that manufactured the component that the BOM describes.",
           "$ref": "#/definitions/organizationalEntity"
         },
         "supplier": {
@@ -868,10 +874,22 @@
           "description": " The organization that supplied the component. The supplier may often be the manufacturer, but may also be a distributor or repackager.",
           "$ref": "#/definitions/organizationalEntity"
         },
+        "manufacturer": {
+          "title": "Component Manufacturer",
+          "description": "The organization that created the component.\nManufacturer is common in components created through automated processes. Components created through manual means may have `@.authors` instead.",
+          "$ref": "#/definitions/organizationalEntity"
+        },
+        "authors" :{
+          "type": "array",
+          "title": "Component Authors",
+          "description": "The person(s) who created the component.\nAuthors are common in components created through manual processes. Components created through automated means may have `@.manufacturer` instead.",
+          "items": {"$ref": "#/definitions/organizationalContact"}
+        },
         "author": {
+          "deprecated": true,
           "type": "string",
-          "title": "Component Author",
-          "description": "The person(s) or organization(s) that authored the component",
+          "title": "Component Author (legacy)",
+          "description": "[Deprecated] - DO NOT USE. This will be removed in a future version. Use `@.authors` or `@.manufacturer` instead.\nThe person(s) or organization(s) that authored the component",
           "examples": ["Acme Inc"]
         },
         "publisher": {

diff --git a/schema/bom-1.6.xsd b/schema/bom-1.6.xsd
@@ -198,8 +198,10 @@ limitations under the License.
             </xs:element>
             <xs:element name="authors" minOccurs="0" maxOccurs="1">
                 <xs:annotation>
-                    <xs:documentation>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.</xs:documentation>
+                    <xs:documentation>
+                        The person(s) who created the BOM.
+                        Authors are common in BOMs created through manual processes. BOMs created through automated means may have './manufacturer' instead.
+                    </xs:documentation>
                 </xs:annotation>
                 <xs:complexType>
                     <xs:sequence minOccurs="0" maxOccurs="unbounded">
@@ -212,9 +214,20 @@ limitations under the License.
                     <xs:documentation>The component that the BOM describes.</xs:documentation>
                 </xs:annotation>
             </xs:element>
+            <xs:element name="manufacturer" type="bom:organizationalEntity" minOccurs="0" maxOccurs="1">
+                <xs:annotation>
+                    <xs:documentation>
+                        The organization that created the BOM.
+                        Manufacturer is common in BOMs created through automated processes. BOMs created through manual means may have './authors' instead.
+                    </xs:documentation>
+                </xs:annotation>
+            </xs:element>
             <xs:element name="manufacture" type="bom:organizationalEntity" minOccurs="0" maxOccurs="1">
                 <xs:annotation>
-                    <xs:documentation>The organization that manufactured the component that the BOM describes.</xs:documentation>
+                    <xs:documentation>
+                        DEPRECATED - DO NOT USE. This will be removed in a future version. Use the `./component/manufacturer` instead.
+                        The organization that manufactured the component that the BOM describes.
+                    </xs:documentation>
                 </xs:annotation>
             </xs:element>
             <xs:element name="supplier" type="bom:organizationalEntity" minOccurs="0" maxOccurs="1">
@@ -483,9 +496,33 @@ limitations under the License.
                         be the manufacturer, but may also be a distributor or repackager.</xs:documentation>
                 </xs:annotation>
             </xs:element>
+            <xs:element name="manufacturer" type="bom:organizationalEntity" minOccurs="0" maxOccurs="1">
+                <xs:annotation>
+                    <xs:documentation>
+                        The organization that created the component.
+                        Manufacturer is common in components created through automated processes. Components created through manual means may have './authors' instead.
+                    </xs:documentation>
+                </xs:annotation>
+            </xs:element>
+            <xs:element name="authors" minOccurs="0" maxOccurs="1">
+                <xs:annotation>
+                    <xs:documentation>
+                        The person(s) who created the component.
+                        Authors are common in components created through manual processes. Components created through automated means may have `./manufacturer` instead.
+                    </xs:documentation>
+                </xs:annotation>
+                <xs:complexType>
+                    <xs:sequence minOccurs="0" maxOccurs="unbounded">
+                        <xs:element name="author" type="bom:organizationalContact"/>
+                    </xs:sequence>
+                </xs:complexType>
+            </xs:element>
             <xs:element name="author" type="xs:normalizedString" minOccurs="0" maxOccurs="1">
                 <xs:annotation>
-                    <xs:documentation>The person(s) or organization(s) that authored the component</xs:documentation>
+                    <xs:documentation>
+                        DEPRECATED - DO NOT USE. This will be removed in a future version. Use `./authors` or `./manufacturer` instead.
+                        The person(s) or organization(s) that authored the component.
+                    </xs:documentation>
                 </xs:annotation>
             </xs:element>
             <xs:element name="publisher" type="xs:normalizedString" minOccurs="0" maxOccurs="1">

diff --git a/tools/src/test/resources/1.6/valid-bom-1.6.json b/tools/src/test/resources/1.6/valid-bom-1.6.json
@@ -45,7 +45,7 @@
         }
       }
     },
-    "manufacture": {
+    "manufacturer": {
       "name": "Acme, Inc.",
       "url": [
         "https://example.com"
@@ -74,6 +74,7 @@
     {
       "bom-ref": "pkg:npm/acme/component@1.0.0",
       "type": "library",
+      "author": "Joane Doe et al.",
       "publisher": "Acme Inc",
       "group": "com.acme",
       "name": "tomcat-catalina",
@@ -160,7 +161,28 @@
           }
         ]
       },
-      "author": "Example Super Heros",
+      "manufacturer": {
+        "name": "Example-2, Inc.",
+        "url": [
+          "https://example.org"
+        ],
+        "contact": [
+          {
+            "email": "support@example.org"
+          }
+        ]
+      },
+      "authors": [
+        {
+          "name": "Anthony Edward Stark",
+          "phone": "555-212-970-4133",
+          "email": "ironman@example.org"
+        },
+        {
+          "name": "Peter Benjamin Parker",
+          "email": "spiderman@example.org"
+        }
+      ],
       "group": "org.example",
       "name": "mylibrary",
       "version": "1.0.0"

diff --git a/tools/src/test/resources/1.6/valid-bom-1.6.textproto b/tools/src/test/resources/1.6/valid-bom-1.6.textproto
@@ -40,26 +40,27 @@ metadata {
       }
     }
   }
-  manufacture {
+  supplier {
     name: "Acme, Inc."
     url: "https://example.com"
     contact {
-      name: "Acme Professional Services"
-      email: "professional.services@example.com"
+      name: "Acme Distribution"
+      email: "distribution@example.com"
     }
   }
-  supplier {
+  manufacturer {
     name: "Acme, Inc."
     url: "https://example.com"
     contact {
-      name: "Acme Distribution"
-      email: "distribution@example.com"
+      name: "Acme Professional Services"
+      email: "professional.services@example.com"
     }
   }
 }
 components {
   type: CLASSIFICATION_LIBRARY
   bom_ref: "pkg:npm/acme/component@1.0.0"
+  author: "Joane Doe et al."
   publisher: "Acme Inc"
   group: "com.acme"
   name: "tomcat-catalina"
@@ -141,6 +142,22 @@ components {
   group: "org.example"
   name: "mylibrary"
   version: "1.0.0"
+  manufacturer {
+    name: "Example-2, Inc."
+    url: "https://example.org"
+    contact {
+      email: "support@example.org"
+    }
+  }
+  authors {
+    name: "Anthony Edward Stark"
+    email: "ironman@example.org"
+    phone: "555-212-970-4133"
+  }
+  authors {
+    name: "Peter Benjamin Parker"
+    email: "spiderman@example.org"
+  }
 }
 dependencies {
   ref: "pkg:npm/acme/component@1.0.0"

diff --git a/tools/src/test/resources/1.6/valid-bom-1.6.xml b/tools/src/test/resources/1.6/valid-bom-1.6.xml
@@ -28,14 +28,14 @@
                 <text content-type="text/xml" encoding="base64">PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiID8+CjxTb2Z0d2FyZUlkZW50aXR5IHhtbDpsYW5nPSJFTiIgbmFtZT0iQWNtZSBBcHBsaWNhdGlvbiIgdmVyc2lvbj0iOS4xLjEiIAogdmVyc2lvblNjaGVtZT0ibXVsdGlwYXJ0bnVtZXJpYyIgCiB0YWdJZD0ic3dpZGdlbi1iNTk1MWFjOS00MmMwLWYzODItM2YxZS1iYzdhMmE0NDk3Y2JfOS4xLjEiIAogeG1sbnM9Imh0dHA6Ly9zdGFuZGFyZHMuaXNvLm9yZy9pc28vMTk3NzAvLTIvMjAxNS9zY2hlbWEueHNkIj4gCiB4bWxuczp4c2k9Imh0dHA6Ly93d3cudzMub3JnLzIwMDEvWE1MU2NoZW1hLWluc3RhbmNlIiAKIHhzaTpzY2hlbWFMb2NhdGlvbj0iaHR0cDovL3N0YW5kYXJkcy5pc28ub3JnL2lzby8xOTc3MC8tMi8yMDE1LWN1cnJlbnQvc2NoZW1hLnhzZCBzY2hlbWEueHNkIiA+CiAgPE1ldGEgZ2VuZXJhdG9yPSJTV0lEIFRhZyBPbmxpbmUgR2VuZXJhdG9yIHYwLjEiIC8+IAogIDxFbnRpdHkgbmFtZT0iQWNtZSwgSW5jLiIgcmVnaWQ9ImV4YW1wbGUuY29tIiByb2xlPSJ0YWdDcmVhdG9yIiAvPiAKPC9Tb2Z0d2FyZUlkZW50aXR5Pg==</text>
             </swid>
         </component>
-        <manufacture>
+        <manufacturer>
             <name>Acme, Inc.</name>
             <url>https://example.com</url>
             <contact>
                 <name>Acme Professional Services</name>
                 <email>professional.services@example.com</email>
             </contact>
-        </manufacture>
+        </manufacturer>
         <supplier>
             <name>Acme, Inc.</name>
             <url>https://example.com</url>
@@ -47,7 +47,7 @@
     </metadata>
     <components>
         <component type="application">
-            <author>Acme Super Heros</author>
+            <author>Joane Doe et al.</author>
             <publisher>Acme Inc</publisher>
             <group>com.acme</group>
             <name>tomcat-catalina</name>
@@ -120,7 +120,24 @@
                     <email>support@apac.example.com</email>
                 </contact>
             </supplier>
-            <author>Example Super Heros</author>
+            <manufacturer>
+                <name>Example-2, Inc.Example-2, Inc.</name>
+                <url>https://example.org</url>
+                <contact>
+                    <email>support@example.org</email>
+                </contact>
+            </manufacturer>
+            <authors>
+                <author>
+                    <name>Anthony Edward Stark</name>
+                    <email>ironman@example.org</email>
+                    <phone>555-212-970-4133</phone>
+                </author>
+                <author>
+                    <name>Peter Benjamin Parker</name>
+                    <email>spiderman@example.org</email>
+                </author>
+            </authors>
             <group>org.example</group>
             <name>mylibrary</name>
             <version>1.0.0</version>

diff --git a/tools/src/test/resources/1.6/valid-metadata-manufacture-1.6.json b/tools/src/test/resources/1.6/valid-metadata-manufacture-1.6.json
@@ -6,7 +6,7 @@
   "metadata": {
     "manufacture": {
       "bom-ref": "manufacturer-1",
-      "name": "Acme, Inc.",
+      "name": "Acme, Inc. // deprecated",
       "url": [
         "https://example.com"
       ],

diff --git a/tools/src/test/resources/1.6/valid-metadata-manufacture-1.6.textproto b/tools/src/test/resources/1.6/valid-metadata-manufacture-1.6.textproto
@@ -3,7 +3,7 @@ version: 1
 serial_number: "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79"
 metadata {
   manufacture {
-    name: "Acme, Inc."
+    name: "Acme, Inc. // deprecated"
     url: "https://example.com"
     contact {
       name: "Acme Professional Services"

diff --git a/tools/src/test/resources/1.6/valid-metadata-manufacture-1.6.xml b/tools/src/test/resources/1.6/valid-metadata-manufacture-1.6.xml
@@ -2,7 +2,7 @@
 <bom serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1" xmlns="http://cyclonedx.org/schema/bom/1.6">
     <metadata>
         <manufacture bom-ref="manufacturer-1">
-            <name>Acme, Inc.</name>
+            <name>Acme, Inc. // deprecated</name>
             <url>https://example.com</url>
             <contact bom-ref="contact-1">
                 <name>Acme Professional Services</name>

diff --git a/tools/src/test/resources/1.6/valid-metadata-manufacturer-1.6.json b/tools/src/test/resources/1.6/valid-metadata-manufacturer-1.6.json
@@ -0,0 +1,23 @@
+{
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.6",
+  "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
+  "version": 1,
+  "metadata": {
+    "manufacturer": {
+      "bom-ref": "manufacturer-1",
+      "name": "Acme, Inc.",
+      "url": [
+        "https://example.com"
+      ],
+      "contact": [
+        {
+          "bom-ref": "contact-1",
+          "name": "Acme Professional Services",
+          "email": "professional.services@example.com"
+        }
+      ]
+    }
+  },
+  "components": []
+}
diff --git a/tools/src/test/resources/1.6/valid-metadata-manufacturer-1.6.textproto b/tools/src/test/resources/1.6/valid-metadata-manufacturer-1.6.textproto
@@ -0,0 +1,15 @@
+spec_version: "1.6"
+version: 1
+serial_number: "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79"
+metadata {
+  manufacturer {
+    name: "Acme, Inc."
+    url: "https://example.com"
+    contact {
+      name: "Acme Professional Services"
+      email: "professional.services@example.com"
+      bom_ref: "contact-1"
+    }
+    bom_ref: "manufacturer-1"
+  }
+}