Skip to content

Commit e9689a5

Browse files
jkowalleckjkowalleck
authored
[1.7] citation: proposed changes 2 (#667)
on top of #630 changes: - ADDED: citation's "attributedTo" may also link to tools -- yes, we have "processes", which are basically tools, but this way it might get more convenient to use citations for BOM generators. - DOCS: streamlined documentation - REFACTOR: reworked the ProtoBuf structures to match some constraints in the the spec -- `choice`/`oneOf` ... - TESTS: practical examples for `citation.expressions`
2 parents bcdcaca + fd1a034 commit e9689a5

File tree

9 files changed

+130
-31
lines changed

9 files changed

+130
-31
lines changed

‎schema/bom-1.7.proto‎

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ message Bom {
4343
repeated Declarations declarations = 14;
4444
// A collection of reusable objects that are defined and may be used elsewhere in the BOM.
4545
repeated Definition definitions = 15;
46-
// Details a specific attribution of data within the BOM to a contributing entity or process.
46+
// A collection of attributions indicating which entity supplied information for specific fields within the BOM.
4747
repeated Citation citations = 16;
4848
}
4949

@@ -2618,20 +2618,38 @@ enum PatentAssertionType {
26182618
PATENT_ASSERTION_TYPE_RESEARCH_OR_EVALUATION = 8;
26192619
}
26202620

2621-
// At least one of the "attributedTo" or "process" elements must be present. This is equivalent to the "anyOf" constraint in the JSON schema.
2621+
// Details a specific attribution of data within the BOM to a contributing entity or process.
26222622
message Citation {
2623+
message Pointers {
2624+
// Users of other serialisation formats (e.g. XML) shall use the JSON Pointer format to ensure consistent field referencing across representations.
2625+
// Must contain at least 1 item.
2626+
repeated string pointer = 1;
2627+
}
2628+
message Expressions {
2629+
// Specifies a path expression used to locate a value within a BOM. The expression syntax shall conform to the format of the BOM's serialisation.
2630+
// Use [JSONPath](https://datatracker.ietf.org/doc/html/rfc9535) for JSON, [XPath](https://www.w3.org/TR/xpath/) for XML, and default to JSONPath for Protocol Buffers unless otherwise specified.
2631+
// Implementers shall ensure the expression is valid within the context of the applicable serialisation format. Use either "pointer" or "expression" but not both in this object.
2632+
// Must contain at least 1 item.
2633+
repeated string expression = 1;
2634+
}
2635+
26232636
// Optional unique identifier for the citation
26242637
optional string bom_ref = 1;
2625-
// One or more JSON Pointers(https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM fields to which the attribution applies.
2626-
repeated string pointer = 2;
2627-
// Specifies a path expression used to locate a value within a BOM. The expression syntax shall conform to the format of the BOM's serialisation. Use [JSONPath](https://datatracker.ietf.org/doc/html/rfc9535) for JSON, [XPath](https://www.w3.org/TR/xpath/) for XML, and default to JSONPath for Protocol Buffers unless otherwise specified. Implementers shall ensure the expression is valid within the context of the applicable serialisation format. Use either "pointer" or "expression" but not both in this object.
2628-
repeated string expression = 3;
2638+
// Exactly one of the "pointers" or "expressions" elements must be present.
2639+
oneof target {
2640+
// One or more JSON Pointers(https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM fields to which the attribution applies.
2641+
Pointers pointers = 2;
2642+
// One or more path expressions used to locate values within a BOM.
2643+
Expressions expressions = 3;
2644+
}
26292645
// Timestamp when the attribution was made or the information was supplied.
26302646
google.protobuf.Timestamp timestamp = 4;
2631-
// The `bom-ref` of an object, such as a component, service, organisational entity, or person that supplied the cited information.
2647+
// The `bom-ref` of an object, such as a component, service, tool, organisational entity, or person that supplied the cited information.
2648+
// At least one of the "attributed_to" or "process" elements must be present.
26322649
optional string attributed_to = 5;
2633-
// An optional `bom-ref` to a process (such as a formula, workflow, task, or step) defined in the `formulation` section that executed or generated the attributed data. At least one of the "attributedTo" or "process" elements must be present.
2650+
// The `bom-ref` to a process (such as a formula, workflow, task, or step) defined in the `formulation` section that executed or generated the attributed data.
2651+
// At least one of the "attributed_to" or "process" elements must be present.
26342652
optional string process = 6;
2635-
// An optional description or comment about the context or quality of the data attribution. At least one of the "attributedTo" or "process" elements must be present.
2653+
// An optional description or comment about the context or quality of the data attribution.
26362654
optional string note = 7;
26372655
}

‎schema/bom-1.7.schema.json‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -532,7 +532,7 @@
532532
"items": {"$ref": "#/definitions/citation"},
533533
"uniqueItems": true,
534534
"title": "Citations",
535-
"description": "A list of attributions indicating which entity supplied information for specific fields within the BOM."
535+
"description": "A collection of attributions indicating which entity supplied information for specific fields within the BOM."
536536
},
537537
"properties": {
538538
"type": "array",
@@ -6125,43 +6125,43 @@
61256125
"$ref": "#/definitions/refType",
61266126
"title": "BOM Reference"
61276127
},
6128-
"attributedTo": {
6129-
"$ref": "#/definitions/refLinkType",
6130-
"title": "Attributed To",
6131-
"description": "The `bom-ref` of an object, such as a component, service, organisational entity, or person that supplied the cited information."
6132-
},
61336128
"pointers": {
61346129
"type": "array",
61356130
"items": {
61366131
"type": "string",
61376132
"title": "Field Reference",
6138-
"description": "A [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM field to which the attribution applies. Users of other serialisation formats (e.g. XML) shall use the JSON Pointer format to ensure consistent field referencing across representations."
6133+
"description": "A [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM field to which the attribution applies.\nUsers of other serialisation formats (e.g. XML) shall use the JSON Pointer format to ensure consistent field referencing across representations."
61396134
},
61406135
"minItems": 1,
61416136
"title": "Field References",
6142-
"description": "One or more [JSON Pointers](https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM fields to which the attribution applies."
6137+
"description": "One or more [JSON Pointers](https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM fields to which the attribution applies.\nExactly one of the \"pointers\" or \"expressions\" elements must be present."
61436138
},
61446139
"expressions": {
61456140
"type": "array",
61466141
"items": {
61476142
"type": "string",
61486143
"title": "Path Expression",
6149-
"description": "Specifies a path expression used to locate a value within a BOM. The expression syntax shall conform to the format of the BOM's serialisation. Use [JSONPath](https://datatracker.ietf.org/doc/html/rfc9535) for JSON, [XPath](https://www.w3.org/TR/xpath/) for XML, and default to JSONPath for Protocol Buffers unless otherwise specified. Implementers shall ensure the expression is valid within the context of the applicable serialisation format."
6144+
"description": "Specifies a path expression used to locate a value within a BOM. The expression syntax shall conform to the format of the BOM's serialisation.\nUse [JSONPath](https://datatracker.ietf.org/doc/html/rfc9535) for JSON, [XPath](https://www.w3.org/TR/xpath/) for XML, and default to JSONPath for Protocol Buffers unless otherwise specified.\nImplementers shall ensure the expression is valid within the context of the applicable serialisation format."
61506145
},
61516146
"minItems": 1,
61526147
"title": "Path Expressions",
6153-
"description": "One or more path expressions used to locate values within a BOM."
6148+
"description": "One or more path expressions used to locate values within a BOM.\nExactly one of the \"pointers\" or \"expressions\" elements must be present."
61546149
},
61556150
"timestamp": {
61566151
"type": "string",
61576152
"format": "date-time",
61586153
"title": "Timestamp",
61596154
"description": "The date and time when the attribution was made or the information was supplied."
61606155
},
6156+
"attributedTo": {
6157+
"$ref": "#/definitions/refLinkType",
6158+
"title": "Attributed To",
6159+
"description": "The `bom-ref` of an object, such as a component, service, tool, organisational entity, or person that supplied the cited information.\nAt least one of the \"attributedTo\" or \"process\" elements must be present."
6160+
},
61616161
"process": {
61626162
"$ref": "#/definitions/refLinkType",
61636163
"title": "Process Reference",
6164-
"description": "An optional `bom-ref` to a process (such as a formula, workflow, task, or step) defined in the `formulation` section that executed or generated the attributed data."
6164+
"description": "The `bom-ref` to a process (such as a formula, workflow, task, or step) defined in the `formulation` section that executed or generated the attributed data.\nAt least one of the \"attributedTo\" or \"process\" elements must be present."
61656165
},
61666166
"note": {
61676167
"type": "string",

‎schema/bom-1.7.xsd‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8883,10 +8883,15 @@ limitations under the License.
88838883
<xs:complexType name="citationType">
88848884
<xs:annotation>
88858885
<xs:documentation>
8886-
At least one of the "attributedTo" or "process" elements must be present. This is equivalent to the "anyOf" constraint in the JSON schema.
8886+
Details a specific attribution of data within the BOM to a contributing entity or process.
88878887
</xs:documentation>
88888888
</xs:annotation>
88898889
<xs:sequence>
8890+
<xs:annotation>
8891+
<xs:documentation>
8892+
Exactly one of the "pointers" or "expressions" elements must be present.
8893+
</xs:documentation>
8894+
</xs:annotation>
88908895
<xs:choice>
88918896
<xs:element name="pointers" minOccurs="1" maxOccurs="1">
88928897
<xs:annotation>
@@ -8899,7 +8904,8 @@ limitations under the License.
88998904
<xs:element name="pointer" type="xs:string" minOccurs="1" maxOccurs="unbounded">
89008905
<xs:annotation>
89018906
<xs:documentation>
8902-
A JSON Pointer(https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM field to which the attribution applies. Users of other serialisation formats (e.g. XML) shall use the JSON Pointer format to ensure consistent field referencing across representations.
8907+
A JSON Pointer(https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM field to which the attribution applies.
8908+
Users of other serialisation formats (e.g. XML) shall use the JSON Pointer format to ensure consistent field referencing across representations.
89038909
</xs:documentation>
89048910
</xs:annotation>
89058911
</xs:element>
@@ -8917,7 +8923,9 @@ limitations under the License.
89178923
<xs:element name="expression" type="xs:string" minOccurs="1" maxOccurs="unbounded">
89188924
<xs:annotation>
89198925
<xs:documentation>
8920-
Specifies a path expression used to locate a value within a BOM. The expression syntax shall conform to the format of the BOM's serialisation. Use [JSONPath](https://datatracker.ietf.org/doc/html/rfc9535) for JSON, [XPath](https://www.w3.org/TR/xpath/) for XML, and default to JSONPath for Protocol Buffers unless otherwise specified. Implementers shall ensure the expression is valid within the context of the applicable serialisation format.
8926+
Specifies a path expression used to locate a value within a BOM. The expression syntax shall conform to the format of the BOM's serialisation.
8927+
Use [JSONPath](https://datatracker.ietf.org/doc/html/rfc9535) for JSON, [XPath](https://www.w3.org/TR/xpath/) for XML, and default to JSONPath for Protocol Buffers unless otherwise specified.
8928+
Implementers shall ensure the expression is valid within the context of the applicable serialisation format.
89218929
</xs:documentation>
89228930
</xs:annotation>
89238931
</xs:element>
@@ -8935,7 +8943,7 @@ limitations under the License.
89358943
<xs:element name="attributedTo" type="bom:refLinkType" minOccurs="0" maxOccurs="1">
89368944
<xs:annotation>
89378945
<xs:documentation>
8938-
The `bom-ref` of an object, such as a component, service, organisational entity, or person that supplied the cited information.
8946+
The `bom-ref` of an object, such as a component, service, tool, organisational entity, or person that supplied the cited information.
89398947
At least one of the "attributedTo" or "process" elements must be present.
89408948
</xs:documentation>
89418949
</xs:annotation>
@@ -9073,7 +9081,7 @@ limitations under the License.
90739081
</xs:element>
90749082
<xs:element name="citations" type="bom:citationsType" minOccurs="0" maxOccurs="1">
90759083
<xs:annotation>
9076-
<xs:documentation>A list of attributions indicating which entity supplied information for specific fields within the BOM.</xs:documentation>
9084+
<xs:documentation>A collection of attributions indicating which entity supplied information for specific fields within the BOM.</xs:documentation>
90779085
</xs:annotation>
90789086
</xs:element>
90799087
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded">

‎tools/src/test/resources/1.7/invalid-citations-1.7.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@
3232
{
3333
"bom-ref": "citation-1",
3434
"pointers": [ "/components/0/name" ],
35-
"expressions": [ "expression here" ],
35+
"expressions": [ "$..[?(@.bom-ref=='component-1')].version" ],
3636
"timestamp": "2025-05-01T14:00:00Z",
3737
"note": "Should not have both a pointer and expression."
3838
}

‎tools/src/test/resources/1.7/invalid-citations-1.7.textproto‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# proto-file: schema/bom-1.7.proto
2+
# proto-message: Bom
3+
4+
spec_version: "1.7"
5+
serial_number: "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79"
6+
version: 1
7+
8+
metadata {
9+
timestamp {
10+
seconds: 1754424907
11+
nanos: 0
12+
}
13+
}
14+
15+
components {
16+
type: CLASSIFICATION_LIBRARY
17+
bom_ref: "component-1"
18+
name: "example-lib"
19+
version: "1.2.3"
20+
licenses {
21+
license {
22+
id: "Apache-2.0"
23+
}
24+
}
25+
}
26+
27+
## !! NO formal check possible
28+
#citations {
29+
# bom_ref: "citation-1"
30+
# pointers: { pointer: "/components/0/name" }
31+
# timestamp {
32+
# seconds: 1746108000
33+
# nanos: 0
34+
# }
35+
# note: "Should have at least one of the following property sets: property 'attributedTo' or property 'process'"
36+
#}
37+
38+
39+
citations {
40+
bom_ref: "citation-1"
41+
pointers: { pointer: "/components/0/name" }
42+
expressions: { expression: "$..[?(bom_ref=='component-1')].version" }
43+
timestamp {
44+
seconds: 1746108000
45+
nanos: 0
46+
}
47+
note: "Should not have both a pointer and expression."
48+
}

‎tools/src/test/resources/1.7/invalid-citations-1.7.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@
8989
<pointer>/components/0/licenses/0/license/id</pointer>
9090
</pointers>
9191
<expressions>
92-
<expression>expression here</expression>
92+
<expression>//*[@bom-ref='component-1']/version</expression>
9393
</expressions>
9494
<timestamp>2025-05-01T14:05:00Z</timestamp>
9595
<process>task-license-scan</process>

‎tools/src/test/resources/1.7/valid-citations-1.7.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,13 @@
4646
},
4747
{
4848
"bom-ref": "citation-3",
49+
"expressions": [ "$..[?(@.bom-ref=='component-1')].version" ],
50+
"timestamp": "2025-05-01T14:00:00Z",
51+
"process": "task-license-scan",
52+
"note": "Semi-manually entered by Alice Example - with `process`"
53+
},
54+
{
55+
"bom-ref": "citation-4",
4956
"expressions": [ "$.components[*].licenses[*].license.id" ],
5057
"timestamp": "2025-05-01T14:05:00Z",
5158
"attributedTo": "scan-tool-1",

‎tools/src/test/resources/1.7/valid-citations-1.7.textproto‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ components {
3232
citations [
3333
{
3434
bom_ref: "citation-1"
35-
pointer: "/components/0/name"
35+
pointers: { pointer: "/components/0/name" }
3636
timestamp: {
3737
seconds: 1746108000
3838
nanos: 0
@@ -41,8 +41,8 @@ citations [
4141
note: "Manually entered by Alice Example"
4242
},
4343
{
44-
bom_ref: "citation-1"
45-
pointer: "/components/0/name"
44+
bom_ref: "citation-2"
45+
pointers: { pointer: "/components/0/name" }
4646
timestamp: {
4747
seconds: 1746108000
4848
nanos: 0
@@ -52,7 +52,17 @@ citations [
5252
},
5353
{
5454
bom_ref: "citation-3"
55-
expression: "$.components[*].licenses[*].license.id"
55+
expressions: { expression: "$..[?(bom_ref=='component-1')].version" }
56+
timestamp: {
57+
seconds: 1746108000
58+
nanos: 0
59+
}
60+
process: "task-license-scan"
61+
note: "Semi-manually entered by Alice Example - with `process`"
62+
},
63+
{
64+
bom_ref: "citation-4"
65+
expressions: { expression: "$.components[*].licenses[*].license.id" }
5666
timestamp: {
5767
seconds: 1746108000
5868
nanos: 0

‎tools/src/test/resources/1.7/valid-citations-1.7.xml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,14 @@
6767
<note>Semi-manually entered by Alice Example - with `process`</note>
6868
</citation>
6969
<citation bom-ref="citation-3">
70+
<expressions>
71+
<expression>//*[@bom-ref='component-1']/version</expression>
72+
</expressions>
73+
<timestamp>2025-05-01T14:00:00Z</timestamp>
74+
<attributedTo>person-1</attributedTo>
75+
<note>Semi-manually entered by Alice Example - with `process`</note>
76+
</citation>
77+
<citation bom-ref="citation-4">
7078
<expressions>
7179
<expression>/components/component/licenses/license/id</expression>
7280
</expressions>

0 commit comments

Comments
 (0)