Skip to content

Commit f315e00

Browse files
stevespringettstevespringett
committed
Added expressions - JSONPath and XPath as an alternative to JSON Pointer. Updated formulation description. Updated test cases.
Signed-off-by: Steve Springett <steve@springett.us>
1 parent 0f225ad commit f315e00

File tree

8 files changed

+102
-40
lines changed

8 files changed

+102
-40
lines changed

‎schema/bom-1.7.proto‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ message Bom {
3737
repeated Annotation annotations = 11;
3838
// Specifies optional, custom, properties
3939
repeated Property properties = 12;
40-
// Describes how a component or service was manufactured or deployed. This is achieved through the use of formulas, workflows, tasks, and steps, which declare the precise steps to reproduce along with the observed formulas describing the steps which transpired in the manufacturing process.
40+
// Describes the formulation of any referencable object within the BOM, including components, services, metadata, declarations, or the BOM itself. This may encompass how the object was created, assembled, deployed, tested, certified, or otherwise brought into its present form. Common examples include software build pipelines, deployment processes, AI/ML model training, cryptographic key generation or certification, and third-party audits. Processes are modeled using declared and observed formulas, composed of workflows, tasks, and individual steps.
4141
repeated Formula formulation = 13;
4242
// The list of declarations which describe the conformance to standards. Each declaration may include attestations, claims, and evidence.
4343
repeated Declarations declarations = 14;
@@ -315,7 +315,7 @@ enum ExternalReferenceType {
315315
EXTERNAL_REFERENCE_TYPE_CONFIGURATION = 35;
316316
// Information used to substantiate a claim.
317317
EXTERNAL_REFERENCE_TYPE_EVIDENCE = 36;
318-
// Describes how a component or service was manufactured or deployed.
318+
// Describes the formulation of any referencable object within the BOM, including components, services, metadata, declarations, or the BOM itself.
319319
EXTERNAL_REFERENCE_TYPE_FORMULATION = 37;
320320
// The location where the source code distributable can be obtained. This is often an archive format such as zip or tar.gz. The source-distribution type complements the use of the version control (vcs) type.
321321
EXTERNAL_REFERENCE_TYPE_SOURCE_DISTRIBUTION = 38;
@@ -2624,12 +2624,14 @@ message Citation {
26242624
optional string bom_ref = 1;
26252625
// One or more JSON Pointers(https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM fields to which the attribution applies.
26262626
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;
26272629
// Timestamp when the attribution was made or the information was supplied.
2628-
google.protobuf.Timestamp timestamp = 3;
2630+
google.protobuf.Timestamp timestamp = 4;
26292631
// The `bom-ref` of an object, such as a component, service, organisational entity, or person that supplied the cited information.
2630-
optional string attributed_to = 4;
2632+
optional string attributed_to = 5;
26312633
// 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.
2632-
optional string process = 5;
2634+
optional string process = 6;
26332635
// 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.
2634-
optional string note = 6;
2636+
optional string note = 7;
26352637
}

‎schema/bom-1.7.schema.json‎

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@
100100
"items": {"$ref": "#/definitions/formula"},
101101
"uniqueItems": true,
102102
"title": "Formulation",
103-
"description": "Describes how a component or service was manufactured or deployed. This is achieved through the use of formulas, workflows, tasks, and steps, which declare the precise steps to reproduce along with the observed formulas describing the steps which transpired in the manufacturing process."
103+
"description": "Describes the formulation of any referencable object within the BOM, including components, services, metadata, declarations, or the BOM itself. This may encompass how the object was created, assembled, deployed, tested, certified, or otherwise brought into its present form. Common examples include software build pipelines, deployment processes, AI/ML model training, cryptographic key generation or certification, and third-party audits. Processes are modeled using declared and observed formulas, composed of workflows, tasks, and individual steps."
104104
},
105105
"declarations": {
106106
"type": "object",
@@ -1932,7 +1932,7 @@
19321932
"log": "A record of events that occurred in a computer system or application, such as problems, errors, or information on current operations.",
19331933
"configuration": "Parameters or settings that may be used by other components or services.",
19341934
"evidence": "Information used to substantiate a claim.",
1935-
"formulation": "Describes how a component or service was manufactured or deployed.",
1935+
"formulation": "Describes the formulation of any referencable object within the BOM, including components, services, metadata, declarations, or the BOM itself.",
19361936
"attestation": "Human or machine-readable statements containing facts, evidence, or testimony.",
19371937
"threat-model": "An enumeration of identified weaknesses, threats, and countermeasures, dataflow diagram (DFD), attack tree, and other supporting documentation in human-readable or machine-readable format.",
19381938
"adversary-model": "The defined assumptions, goals, and capabilities of an adversary.",
@@ -6140,6 +6140,17 @@
61406140
"title": "Field References",
61416141
"description": "One or more [JSON Pointers](https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM fields to which the attribution applies."
61426142
},
6143+
"expressions": {
6144+
"type": "array",
6145+
"items": {
6146+
"type": "string",
6147+
"title": "Path Expression",
6148+
"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."
6149+
},
6150+
"minItems": 1,
6151+
"title": "Path Expressions",
6152+
"description": "One or more path expressions used to locate values within a BOM."
6153+
},
61436154
"timestamp": {
61446155
"type": "string",
61456156
"format": "date-time",
@@ -6162,10 +6173,14 @@
61626173
"description": "An optional digital signature verifying the authenticity or integrity of the attribution."
61636174
}
61646175
},
6165-
"required": ["pointers", "timestamp"],
6176+
"required": ["timestamp"],
61666177
"anyOf": [
61676178
{ "required": ["attributedTo"] },
61686179
{ "required": ["process"] }
6180+
],
6181+
"oneOf": [
6182+
{ "required": ["pointers"] },
6183+
{ "required": ["expressions"] }
61696184
]
61706185
}
61716186
}

‎schema/bom-1.7.xsd‎

Lines changed: 53 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1669,7 +1669,7 @@ limitations under the License.
16691669
</xs:enumeration>
16701670
<xs:enumeration value="formulation">
16711671
<xs:annotation>
1672-
<xs:documentation>Describes how a component or service was manufactured or deployed.</xs:documentation>
1672+
<xs:documentation>Describes the formulation of any referencable object within the BOM, including components, services, metadata, declarations, or the BOM itself.</xs:documentation>
16731673
</xs:annotation>
16741674
</xs:enumeration>
16751675
<xs:enumeration value="attestation">
@@ -5218,9 +5218,13 @@ limitations under the License.
52185218
<xs:complexType name="formulationType">
52195219
<xs:annotation>
52205220
<xs:documentation>
5221-
Describes how a component or service was manufactured or deployed. This is achieved through the use
5222-
of formulas, workflows, tasks, and steps, which declare the precise steps to reproduce along with the
5223-
observed formulas describing the steps which transpired in the manufacturing process.
5221+
Describes the formulation of any referencable object within the BOM,
5222+
including components, services, metadata, declarations, or the BOM itself. This may
5223+
encompass how the object was created, assembled, deployed, tested, certified, or otherwise
5224+
brought into its present form. Common examples include software build pipelines,
5225+
deployment processes, AI/ML model training, cryptographic key generation or certification,
5226+
and third-party audits. Processes are modeled using declared and observed formulas,
5227+
composed of workflows, tasks, and individual steps.
52245228
</xs:documentation>
52255229
</xs:annotation>
52265230
<xs:sequence minOccurs="0" maxOccurs="unbounded">
@@ -8880,24 +8884,44 @@ limitations under the License.
88808884
</xs:documentation>
88818885
</xs:annotation>
88828886
<xs:sequence>
8883-
<xs:element name="pointers" minOccurs="1" maxOccurs="1">
8884-
<xs:annotation>
8885-
<xs:documentation>
8886-
One or more JSON Pointers(https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM fields to which the attribution applies.
8887-
</xs:documentation>
8888-
</xs:annotation>
8889-
<xs:complexType>
8890-
<xs:sequence>
8891-
<xs:element name="pointer" type="xs:string" minOccurs="1" maxOccurs="unbounded">
8892-
<xs:annotation>
8893-
<xs:documentation>
8894-
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.
8895-
</xs:documentation>
8896-
</xs:annotation>
8897-
</xs:element>
8898-
</xs:sequence>
8899-
</xs:complexType>
8900-
</xs:element>
8887+
<xs:choice>
8888+
<xs:element name="pointers" minOccurs="1" maxOccurs="1">
8889+
<xs:annotation>
8890+
<xs:documentation>
8891+
One or more JSON Pointers(https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM fields to which the attribution applies.
8892+
</xs:documentation>
8893+
</xs:annotation>
8894+
<xs:complexType>
8895+
<xs:sequence>
8896+
<xs:element name="pointer" type="xs:string" minOccurs="1" maxOccurs="unbounded">
8897+
<xs:annotation>
8898+
<xs:documentation>
8899+
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.
8900+
</xs:documentation>
8901+
</xs:annotation>
8902+
</xs:element>
8903+
</xs:sequence>
8904+
</xs:complexType>
8905+
</xs:element>
8906+
<xs:element name="expressions" minOccurs="1" maxOccurs="1">
8907+
<xs:annotation>
8908+
<xs:documentation>
8909+
One or more path expressions used to locate values within a BOM.
8910+
</xs:documentation>
8911+
</xs:annotation>
8912+
<xs:complexType>
8913+
<xs:sequence>
8914+
<xs:element name="expression" type="xs:string" minOccurs="1" maxOccurs="unbounded">
8915+
<xs:annotation>
8916+
<xs:documentation>
8917+
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.
8918+
</xs:documentation>
8919+
</xs:annotation>
8920+
</xs:element>
8921+
</xs:sequence>
8922+
</xs:complexType>
8923+
</xs:element>
8924+
</xs:choice>
89018925
<xs:element name="timestamp" type="xs:dateTime" minOccurs="1" maxOccurs="1">
89028926
<xs:annotation>
89038927
<xs:documentation>
@@ -9020,10 +9044,13 @@ limitations under the License.
90209044
</xs:element>
90219045
<xs:element name="formulation" type="bom:formulationType" minOccurs="0" maxOccurs="1">
90229046
<xs:annotation>
9023-
<xs:documentation>Describes how a component or service was manufactured or deployed. This is
9024-
achieved through the use of formulas, workflows, tasks, and steps, which declare the precise
9025-
steps to reproduce along with the observed formulas describing the steps which transpired
9026-
in the manufacturing process.</xs:documentation>
9047+
<xs:documentation>Describes the formulation of any referencable object within the BOM,
9048+
including components, services, metadata, declarations, or the BOM itself. This may
9049+
encompass how the object was created, assembled, deployed, tested, certified, or otherwise
9050+
brought into its present form. Common examples include software build pipelines,
9051+
deployment processes, AI/ML model training, cryptographic key generation or certification,
9052+
and third-party audits. Processes are modeled using declared and observed formulas,
9053+
composed of workflows, tasks, and individual steps.</xs:documentation>
90279054
</xs:annotation>
90289055
</xs:element>
90299056
<xs:element name="declarations" type="bom:declarationsType" minOccurs="0" maxOccurs="1">

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,13 @@
2828
"pointers": [ "/components/0/name" ],
2929
"timestamp": "2025-05-01T14:00:00Z",
3030
"note": "Should have at least one of the following property sets: property 'attributedTo' or property 'process'"
31+
},
32+
{
33+
"bom-ref": "citation-1",
34+
"pointers": [ "/components/0/name" ],
35+
"expressions": [ "expression here" ],
36+
"timestamp": "2025-05-01T14:00:00Z",
37+
"note": "Should not have both a pointer and expression."
3138
}
3239
]
3340
}

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,5 +84,16 @@
8484
<process>task-license-scan-2</process>
8585
<note>Should have at max one 'process'</note>
8686
</citation>
87+
<citation bom-ref="citation-4">
88+
<pointers>
89+
<pointer>/components/0/licenses/0/license/id</pointer>
90+
</pointers>
91+
<expressions>
92+
<expression>expression here</expression>
93+
</expressions>
94+
<timestamp>2025-05-01T14:05:00Z</timestamp>
95+
<process>task-license-scan</process>
96+
<note>Should not have both a pointer and expression.</note>
97+
</citation>
8798
</citations>
8899
</bom>

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@
4646
},
4747
{
4848
"bom-ref": "citation-3",
49-
"pointers": [ "/components/0/licenses/0/license/id" ],
49+
"expressions": [ "$.components[*].licenses[*].license.id" ],
5050
"timestamp": "2025-05-01T14:05:00Z",
5151
"attributedTo": "scan-tool-1",
5252
"process": "task-license-scan",

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ citations [
5252
},
5353
{
5454
bom_ref: "citation-3"
55-
pointer: "/components/0/licenses/0/license/id"
55+
expression: "$.components[*].licenses[*].license.id"
5656
timestamp: {
5757
seconds: 1746108000
5858
nanos: 0

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -67,9 +67,9 @@
6767
<note>Semi-manually entered by Alice Example - with `process`</note>
6868
</citation>
6969
<citation bom-ref="citation-3">
70-
<pointers>
71-
<pointer>/components/0/licenses/0/license/id</pointer>
72-
</pointers>
70+
<expressions>
71+
<expression>/components/component/licenses/license/id</expression>
72+
</expressions>
7373
<timestamp>2025-05-01T14:05:00Z</timestamp>
7474
<attributedTo>scan-tool-1</attributedTo>
7575
<process>task-license-scan</process>

0 commit comments

Comments
 (0)