Skip to content

Commit df38bf5

Browse files
stevespringettstevespringett
authored
Merge pull request #169 from CycloneDX/v1.5-dev-annotations
Add annotations support and valid test cases
2 parents 32e87a9 + d3f4cbe commit df38bf5

File tree

6 files changed

+525
-1
lines changed

6 files changed

+525
-1
lines changed

‎schema/bom-1.5.proto‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,10 @@ message Bom {
3333
repeated Composition compositions = 9;
3434
// Vulnerabilities identified in components or services.
3535
repeated Vulnerability vulnerabilities = 10;
36+
// Comments made by people, organizations, or tools about any object with a bom-ref, such as components, services, vulnerabilities, or the BOM itself. Unlike inventory information, annotations may contain opinion or commentary from various stakeholders.
37+
repeated Annotation annotations = 11;
3638
// Specifies optional, custom, properties
37-
repeated Property properties = 11;
39+
repeated Property properties = 12;
3840
}
3941

4042
enum Classification {
@@ -749,3 +751,29 @@ enum VulnerabilityAffectedStatus {
749751
VULNERABILITY_AFFECTED_STATUS_AFFECTED = 1;
750752
VULNERABILITY_AFFECTED_STATUS_NOT_AFFECTED = 2;
751753
}
754+
755+
message AnnotatorChoice {
756+
oneof choice {
757+
// The organization that created the annotation
758+
OrganizationalEntity organization = 1;
759+
// The person that created the annotation
760+
OrganizationalContact individual = 2;
761+
// The tool or component that created the annotation
762+
Component component = 3;
763+
// The service that created the annotation
764+
Service service = 4;
765+
}
766+
}
767+
768+
message Annotation {
769+
// An optional identifier which can be used to reference the annotation elsewhere in the BOM. Every bom-ref MUST be unique within the BOM.
770+
optional string bom_ref = 1;
771+
// The object in the BOM identified by its bom-ref. This is often a component or service, but may be any object type supporting bom-refs.
772+
repeated string subjects = 2;
773+
// The organization, person, component, or service which created the textual content of the annotation.
774+
AnnotatorChoice annotator = 3;
775+
// The date and time (timestamp) when the annotation was created.
776+
google.protobuf.Timestamp timestamp = 4;
777+
// The textual content of the annotation.
778+
string text = 5;
779+
}

‎schema/bom-1.5.schema.json‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,14 @@
9797
"title": "Vulnerabilities",
9898
"description": "Vulnerabilities identified in components or services."
9999
},
100+
"annotations": {
101+
"type": "array",
102+
"additionalItems": false,
103+
"items": {"$ref": "#/definitions/annotations"},
104+
"uniqueItems": true,
105+
"title": "Annotations",
106+
"description": "Comments made by people, organizations, or tools about any object with a bom-ref, such as components, services, vulnerabilities, or the BOM itself. Unlike inventory information, annotations may contain opinion or commentary from various stakeholders. Annotations may be inline (with inventory) or externalized via BOM-Link, and may optionally be signed."
107+
},
100108
"properties": {
101109
"type": "array",
102110
"title": "Properties",
@@ -1857,6 +1865,97 @@
18571865
"minLength": 1,
18581866
"maxLength": 1024
18591867
},
1868+
"annotations": {
1869+
"type": "object",
1870+
"title": "Annotations",
1871+
"description": "A comment, note, explanation, or similar textual content which provides additional context to the object(s) being annotated.",
1872+
"required": [
1873+
"subjects",
1874+
"annotator",
1875+
"timestamp",
1876+
"text"
1877+
],
1878+
"additionalProperties": false,
1879+
"properties": {
1880+
"bom-ref": {
1881+
"$ref": "#/definitions/refType",
1882+
"title": "BOM Reference",
1883+
"description": "An optional identifier which can be used to reference the annotation elsewhere in the BOM. Every bom-ref MUST be unique within the BOM."
1884+
},
1885+
"subjects": {
1886+
"type": "array",
1887+
"uniqueItems": true,
1888+
"additionalItems": false,
1889+
"items": {
1890+
"$ref": "#/definitions/refType"
1891+
},
1892+
"title": "BOM References",
1893+
"description": "The object in the BOM identified by its bom-ref. This is often a component or service, but may be any object type supporting bom-refs."
1894+
},
1895+
"annotator": {
1896+
"type": "object",
1897+
"title": "Annotator",
1898+
"description": "The organization, person, component, or service which created the textual content of the annotation.",
1899+
"oneOf": [
1900+
{
1901+
"required": [
1902+
"organization"
1903+
]
1904+
},
1905+
{
1906+
"required": [
1907+
"individual"
1908+
]
1909+
},
1910+
{
1911+
"required": [
1912+
"component"
1913+
]
1914+
},
1915+
{
1916+
"required": [
1917+
"service"
1918+
]
1919+
}
1920+
],
1921+
"additionalProperties": false,
1922+
"properties": {
1923+
"organization": {
1924+
"description": "The organization that created the annotation",
1925+
"$ref": "#/definitions/organizationalEntity"
1926+
},
1927+
"individual": {
1928+
"description": "The person that created the annotation",
1929+
"$ref": "#/definitions/organizationalContact"
1930+
},
1931+
"component": {
1932+
"description": "The tool or component that created the annotation",
1933+
"$ref": "#/definitions/component"
1934+
},
1935+
"service": {
1936+
"description": "The service that created the annotation",
1937+
"$ref": "#/definitions/service"
1938+
}
1939+
}
1940+
},
1941+
"timestamp": {
1942+
"type": "string",
1943+
"format": "date-time",
1944+
"title": "Timestamp",
1945+
"description": "The date and time (timestamp) when the annotation was created."
1946+
},
1947+
"text": {
1948+
"type": "string",
1949+
"title": "Text",
1950+
"description": "The textual content of the annotation."
1951+
},
1952+
"signature": {
1953+
"$ref": "#/definitions/signature",
1954+
"title": "Signature",
1955+
"description": "Enveloped signature in [JSON Signature Format (JSF)](https://cyberphone.github.io/doc/security/jsf.html)."
1956+
}
1957+
}
1958+
},
18601959
"signature": {
18611960
"$ref": "jsf-0.82.schema.json#/definitions/signature",
18621961
"title": "Signature",

‎schema/bom-1.5.xsd‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2368,6 +2368,111 @@ limitations under the License.
23682368
</xs:sequence>
23692369
</xs:complexType>
23702370

2371+
<xs:complexType name="annotationsType">
2372+
<xs:sequence minOccurs="0" maxOccurs="unbounded">
2373+
<xs:element name="annotation" type="bom:annotationType"/>
2374+
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded">
2375+
<xs:annotation>
2376+
<xs:documentation>
2377+
Allows any undeclared elements as long as the elements are placed in a different namespace.
2378+
</xs:documentation>
2379+
</xs:annotation>
2380+
</xs:any>
2381+
</xs:sequence>
2382+
<xs:anyAttribute namespace="##any" processContents="lax">
2383+
<xs:annotation>
2384+
<xs:documentation>User-defined attributes may be used on this element as long as they
2385+
do not have the same name as an existing attribute used by the schema.</xs:documentation>
2386+
</xs:annotation>
2387+
</xs:anyAttribute>
2388+
</xs:complexType>
2389+
2390+
<xs:complexType name="annotatorChoiceType">
2391+
<xs:choice>
2392+
<xs:element name="organization" type="bom:organizationalEntity" minOccurs="0" maxOccurs="1">
2393+
<xs:annotation>
2394+
<xs:documentation>The organization that created the annotation</xs:documentation>
2395+
</xs:annotation>
2396+
</xs:element>
2397+
<xs:element name="individual" type="bom:organizationalContact" minOccurs="0" maxOccurs="1">
2398+
<xs:annotation>
2399+
<xs:documentation>The person that created the annotation</xs:documentation>
2400+
</xs:annotation>
2401+
</xs:element>
2402+
<xs:element name="component" type="bom:component" minOccurs="0" maxOccurs="1">
2403+
<xs:annotation>
2404+
<xs:documentation>The tool or component that created the annotation</xs:documentation>
2405+
</xs:annotation>
2406+
</xs:element>
2407+
<xs:element name="service" type="bom:service" minOccurs="0" maxOccurs="1">
2408+
<xs:annotation>
2409+
<xs:documentation>The service that created the annotation</xs:documentation>
2410+
</xs:annotation>
2411+
</xs:element>
2412+
</xs:choice>
2413+
</xs:complexType>
2414+
2415+
<xs:complexType name="annotationType">
2416+
<xs:sequence>
2417+
<xs:element name="subjects" minOccurs="0" maxOccurs="1">
2418+
<xs:annotation>
2419+
<xs:documentation>
2420+
The objects in the BOM identified by their bom-ref's. This is often components or services, but may be any object type supporting bom-refs.
2421+
</xs:documentation>
2422+
</xs:annotation>
2423+
<xs:complexType>
2424+
<xs:sequence minOccurs="0" maxOccurs="unbounded">
2425+
<xs:element name="subject" type="bom:bomReferenceType"/>
2426+
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded">
2427+
<xs:annotation>
2428+
<xs:documentation>
2429+
Allows any undeclared elements as long as the elements are placed in a different namespace.
2430+
</xs:documentation>
2431+
</xs:annotation>
2432+
</xs:any>
2433+
</xs:sequence>
2434+
</xs:complexType>
2435+
</xs:element>
2436+
<xs:element name="annotator" type="bom:annotatorChoiceType" minOccurs="1" maxOccurs="1">
2437+
<xs:annotation>
2438+
<xs:documentation>The organization, individual, component, or service which created the textual content
2439+
of the annotation.</xs:documentation>
2440+
</xs:annotation>
2441+
</xs:element>
2442+
<xs:element name="timestamp" type="xs:dateTime" minOccurs="1" maxOccurs="1">
2443+
<xs:annotation>
2444+
<xs:documentation>The date and time (timestamp) when the annotation was created.</xs:documentation>
2445+
</xs:annotation>
2446+
</xs:element>
2447+
<xs:element name="text" type="xs:string" minOccurs="1" maxOccurs="1">
2448+
<xs:annotation>
2449+
<xs:documentation>The textual content of the annotation.</xs:documentation>
2450+
</xs:annotation>
2451+
</xs:element>
2452+
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded">
2453+
<xs:annotation>
2454+
<xs:documentation>
2455+
Allows any undeclared elements as long as the elements are placed in a different namespace.
2456+
</xs:documentation>
2457+
</xs:annotation>
2458+
</xs:any>
2459+
</xs:sequence>
2460+
<xs:attribute name="bom-ref" type="bom:refType">
2461+
<xs:annotation>
2462+
<xs:documentation>
2463+
An optional identifier which can be used to reference the annotation elsewhere in the BOM.
2464+
Uniqueness is enforced within all elements and children of the root-level bom element.
2465+
</xs:documentation>
2466+
</xs:annotation>
2467+
</xs:attribute>
2468+
<xs:anyAttribute namespace="##any" processContents="lax">
2469+
<xs:annotation>
2470+
<xs:documentation>User-defined attributes may be used on this element as long as they
2471+
do not have the same name as an existing attribute used by the schema.</xs:documentation>
2472+
</xs:annotation>
2473+
</xs:anyAttribute>
2474+
</xs:complexType>
2475+
23712476
<xs:simpleType name="severityType" final="restriction">
23722477
<xs:annotation>
23732478
<xs:documentation xml:lang="en">
@@ -2644,6 +2749,15 @@ limitations under the License.
26442749
<xs:documentation>Vulnerabilities identified in components or services.</xs:documentation>
26452750
</xs:annotation>
26462751
</xs:element>
2752+
<xs:element name="annotations" type="bom:annotationsType" minOccurs="0" maxOccurs="1">
2753+
<xs:annotation>
2754+
<xs:documentation>Comments made by people, organizations, or tools about any object with
2755+
a bom-ref, such as components, services, vulnerabilities, or the BOM itself. Unlike
2756+
inventory information, annotations may contain opinion or commentary from various
2757+
stakeholders. Annotations may be inline (with inventory) or externalized via BOM-Link,
2758+
and may optionally be signed.</xs:documentation>
2759+
</xs:annotation>
2760+
</xs:element>
26472761
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded">
26482762
<xs:annotation>
26492763
<xs:documentation>

‎tools/src/test/resources/1.5/valid-annotation-1.5.json‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
{
2+
"bomFormat": "CycloneDX",
3+
"specVersion": "1.5",
4+
"serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
5+
"version": 1,
6+
"components": [
7+
{
8+
"bom-ref": "component-a",
9+
"type": "library",
10+
"name": "Component A",
11+
"version": "1.0.0"
12+
}
13+
],
14+
"annotations": [
15+
{
16+
"bom-ref": "annotation-1",
17+
"subjects": [
18+
"component-a"
19+
],
20+
"annotator": {
21+
"organization": {
22+
"name": "Acme, Inc.",
23+
"url": [
24+
"https://example.com"
25+
],
26+
"contact": [
27+
{
28+
"name": "Acme Professional Services",
29+
"email": "[email protected]"
30+
}
31+
]
32+
}
33+
},
34+
"timestamp": "2022-01-01T00:00:00Z",
35+
"text": "This is a sample annotation made by an organization"
36+
},
37+
{
38+
"bom-ref": "annotation-2",
39+
"subjects": [
40+
"component-a"
41+
],
42+
"annotator": {
43+
"individual": {
44+
"name": "Samantha Wright",
45+
"email": "[email protected]",
46+
"phone": "800-555-1212"
47+
}
48+
},
49+
"timestamp": "2022-01-01T00:00:00Z",
50+
"text": "This is a sample annotation made by a person"
51+
},
52+
{
53+
"bom-ref": "annotation-3",
54+
"subjects": [
55+
"component-a"
56+
],
57+
"annotator": {
58+
"component": {
59+
"type": "application",
60+
"name": "Awesome Tool",
61+
"version": "9.1.2"
62+
}
63+
},
64+
"timestamp": "2022-01-01T00:00:00Z",
65+
"text": "This is a sample annotation made by a component"
66+
},
67+
{
68+
"bom-ref": "annotation-4",
69+
"subjects": [
70+
"component-a"
71+
],
72+
"annotator": {
73+
"service": {
74+
"bom-ref": "b2a46a4b-8367-4bae-9820-95557cfe03a8",
75+
"provider": {
76+
"name": "Partner Org",
77+
"url": [
78+
"https://partner.org"
79+
]
80+
},
81+
"group": "org.partner",
82+
"name": "BOM Annotation Service",
83+
"version": "2020-Q2",
84+
"endpoints": [
85+
"https://partner.org/api/v1/inspect",
86+
"https://partner.org/api/v1/annotate"
87+
],
88+
"authenticated": true,
89+
"x-trust-boundary": true,
90+
"data": [
91+
{
92+
"classification": "public",
93+
"flow": "bi-directional"
94+
}
95+
]
96+
}
97+
},
98+
"timestamp": "2022-01-01T00:00:00Z",
99+
"text": "This is a sample annotation made by a service"
100+
}
101+
]
102+
}

0 commit comments

Comments
 (0)