jkowalleck
commented
1 year ago Interesting proposal.
I really like the implicated outcome and benefits. But I doubt that your solution covers it properly. And here is why:
So you want to link to external documents via externalReference.
These documents might be not under your control and might change without notice.
These external documents, might be bound to XML/JSON schema, which these documents usually announce themselves internally.
- XML has a one/multiple schema/namespace attributes, might change schema/namespace from one node to another, ... is per definition extensible.
Furthermore, XML not only knows XSD but also DTD. - JSON knows JSON-schema, it might announce it via a root property
$schema.
I find it to be BAD idea to announce the schema of a foreign document externally. Downstream users need to download/read the document anyway, to check if the claim in the SBOM was correct.
From a technical perspective, it is impossible to point an XML to exactly one schema.
From a technical perspective, XML/JSON schemas are extensible. I could create a superset of your schema, and be still compliant with your schema. Still, I would announce my schema, not yours. So if you are scanning a BOM for externalReferences that apply to your schema, you would not find my document, even if it is compliant to your schema. A false-negative.
Let me reverse engineer your thought process and start with the requirements engineering. (A friendly reminder: It might really help, if you could describe constraints and desired capabilities, not just give some reasons why a proposed solution is sufficient for a set of users)
SO your case is enabling BOM users to understand the explicit usage of an externalReferenced document, right?
externalReference already has properties url, type, comment and hashes.
You claim that type is not enough.
If I understand your original proposed solution correctly, the idea of linking a Schema comes from the following aspects:
- current ENUM values of
externalReference.typeare insufficient for you - you need a property of
externalReferenceto store the use-case(s) of a referenced document. The value range of this "use-case" is about to expand, why you want to use arbitrary strings, instead of an ENUM. The value should be free. The value should be kind of universal, so that a kind of standards exists.
Then here is my alternative proposal for a solution
Add a new property externalReference.purposes that is an ENUM which is managed outside the CycloneDX schema.
The document that manages the purposes can be short living and be extended/updated independently of the CycloneDX schema and its life cycle. Just like the "SPDX" license ID in CycloneDX is managed already.
The following code is untested...
Example schema
-
{ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "http://cyclonedx.org/schema/bom-1.5.schema.json", "definitions": { "externalReference": { "type": "object", "title": "External Reference", // the existing things ... "properties": { // the existing things ... "purposes": { "type": "array", "items": { "allOf": [ { "type": "string", "title": "Purpose" }, { "$ref": "http://cyclonedx.org/schema/externalReference-purposes.schema.json" } ] } } } } -
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" xmlns:bom="http://cyclonedx.org/schema/bom/1.5" xmlns:externalReferencePurposes"http://cyclonedx.org/schema/externalReferencePurposes" > <xs:import namespace="http://cyclonedx.org/schema/externalReferencePurposes" schemaLocation="http://cyclonedx.org/schema/externalReferencePurposes.xsd"/> <xs:complexType name="externalReference"> <xs:sequence> <!-- the existing things ... --> <xs:element name="purposes" minOccurs="0" maxOccurs="1"> <xs:complexType> <xs:sequence minOccurs="0" maxOccurs="unbounded"> <xs:element name="purpose" type="externalReferencePurposes:values"/> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> <xs:schema>
Example externalReference-purposes.schema.json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://cyclonedx.org/schema/externalReference-purposes.schema.json",
"$comment": "v1.0",
"enum": [
"Foo"
// some values here
]
}Example externalReferencePurposes.xsd
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
targetNamespace="http://cyclonedx.org/schema/externalReferencePurposes"
version="1.0">
<xs:simpleType name="values">
<xs:restriction base="xs:string">
<xs:enumeration value="Foo"/>
<!-- some values here -->
</xs:restriction>
</xs:simpleType>
</xs:schema>
mrutkows
stevespringett
In discussions being had within the ML work group around "model cards" we ack. that the in-progress CycloneDX schema to describe ML models has, at best ad-hoc standards to draw common data from. Specifically, we have found various structured and unstructured data being presented specific to ML service providers (e.g., Google, AWS, IBM, etc.) and ML catalogs such as HuggingFace and projects like Tensorflow. Therefore, our approach is to adopt basic data objects and fields that make sense of the commonality we have found, but wish to allow for providers to reference descriptors (e.g., schemas) for their specific model information (data inputs, outputs, statistical analysis, imaging, etc.) using the
"externalReference"objects. It would be helpful for automation, to know for validation or visualization purposes, if the referenced data has a published schema (e.g., in XSD or JSON) to apply against the information/data pointed to by the"url"field.As we support new XBOM types (e.g., Crypto CBOM, Machine Learning MLBOM, etc.) we will encounter more and more domain-specific data (hopefully with structure schemas) and it was encouraged the I take my proposal to add a
"schema"field to the"externalReference"to make the reference more meaningful in those cases.Applicability to existing reference types:
General types
"bom"
"build-meta"
Specific Types
Hopefully, you can see from these few examples (and perhaps suggest new "type" values for the enum field) the value of adding the
"schema"field with an associated data type that reflects a URI (or the more generalized for IRI). This might appear in the "ExternalReference" definition as follows:Note: we may also want to add a complimentary field such as to disambiguate what schema version (draft) of either XML schema or JSON schema was used as well... shown above as
"schemaType".