CycloneDX
[FEATURE] xml catalog for XSD
Adding an XML catalog file and corresponding Java unit tests to validate the XML catalog content match local XSD file content.
Please see also: https://github.com/CycloneDX/specification/pull/477
I needed to modify the pom.xml to include the path to the schema/ folder. This might not be a Java/maven best practice, but given how the folders are organised, I have no other solutions without changing the folders location:
Access "/home/user/cyclonedx-specification.thalesgroup/tools/../schema" directory outside of project base directory. (org.apache.maven.plugins:maven-resources-plugin:3.3.1:testResources:default-testResources:process-test-resources)
Java unit tests seem okay, see picture below:
java --version
openjdk 22 2024-03-19
OpenJDK Runtime Environment (build 22)
OpenJDK 64-Bit Server VM (build 22, mixed mode, sharing)
Thanks for the PR. I think the addition of an xmlcatalog is fine, however, I don't think that /schema is the proper place to put it. Every file in that directory is part of the CycloneDX specification or supports it directly. Adding a file that is not part of the specification seems odd to me. Does this belong in /tools/src/test/resources/schema perhaps?
Every file in that directory is part [
schema/] of the CycloneDX specification or supports it directly.
One could say that the XML catalogs directly supports the CycloneDX specification XSD files by providing a way to bind local filepath with schema URI / namespace, even in an environment disconnected from the internet. So in that sense, the XML catalog file schema/xmlcatalog.xml should be under schema/, because it is part of the schema name resolution.
But the content of the xmlcatalog.xml file depends on paths... So if you move the file xmlcatalog.xml and or move the XSD files, you need to adjust path in xmlcatalog.xml.
Does this belong in
/tools/src/test/resources/schemaperhaps?
I personally do not consider the xmlcatalog.xml to be a test resource.
But let me remind you why I did this PR in the first place...
Lets compare XSD files from https://github.com/CycloneDX/cyclonedx-go/ and https://github.com/CycloneDX/specification.
I notice the schemaLocation fields for SPDX XSD are different depending on the project:
| Project | schemaLocation for SPDX XSD |
|---|---|
| github.com/CycloneDX/specification | schemaLocation="http://cyclonedx.org/schema/spdx |
| github.com/CycloneDX/cyclonedx-go | schemaLocation="spdx.xsd |
| github.com/CycloneDX/cyclonedx-core-java | schemaLocation="http://cyclonedx.org/schema/spdx" |
| github.com/CycloneDX/cyclonedx-python-lib | schemaLocation="spdx.SNAPSHOT.xsd" |
CycloneDX/cyclonedx-python-lib even gives an explanation in CycloneDX/cyclonedx-python-lib/cyclonedx/schema/_res/README.md to what modifications are made between the repo CycloneDX/specification and the python one.
This makes more difficult to use the CycloneDX schemas, as there are as many CycloneDX schemas as there are implementation.
Below are the results of commands:
git clone github.com/CycloneDX/cyclonedx-go
git clone github.com/CycloneDX/specification
diff cyclonedx-go/schema/bom-1.x.xsd specification/schema/bom-1.x.xsd
diff cyclonedx-go/schema/bom-1.0.xsd specification/schema/bom-1.0.xsd
q12c12
< <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="spdx.xsd"/>
---
> <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="http://cyclonedx.org/schema/spdx"/>
diff cyclonedx-go/schema/bom-1.1.xsd specification/schema/bom-1.1.xsd
27c27
< <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="spdx.xsd"/>
---
> <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="http://cyclonedx.org/schema/spdx"/>
diff cyclonedx-go/schema/bom-1.2.xsd specification/schema/bom-1.2.xsd
27c27
< <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="spdx.xsd"/>
---
> <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="http://cyclonedx.org/schema/spdx"/>
diff cyclonedx-go/schema/bom-1.3.xsd specification/schema/bom-1.3.xsd
27c27
< <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="spdx.xsd"/>
---
> <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="http://cyclonedx.org/schema/spdx"/>
diff cyclonedx-go/schema/bom-1.4.xsd specification/schema/bom-1.4.xsd
27c27
< <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="spdx.xsd"/>
---
> <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="http://cyclonedx.org/schema/spdx"/>
diff cyclonedx-go/schema/bom-1.5.xsd specification/schema/bom-1.5.xsd
Expands
27c27
< <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="spdx.xsd"/>
---
> <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="http://cyclonedx.org/schema/spdx"/>
477c477
< <xs:element name="scope" type="bom:scope" minOccurs="0" maxOccurs="1">
---
> <xs:element name="scope" type="bom:scope" minOccurs="0" maxOccurs="1" default="required">
799,800c799,800
< </xs:annotation>
< </xs:element>
---
> </xs:annotation>
> </xs:element>
1804,1807c1804,1809
< <xs:documentation>Components that do not have their own dependencies MUST be declared as empty
< elements within the graph. Components that are not represented in the dependency graph MAY
< have unknown dependencies. It is RECOMMENDED that implementations assume this to be opaque
< and not an indicator of a component being dependency-free.</xs:documentation>
---
> <xs:documentation>Defines the direct dependencies of a component or service. Components or services
> that do not have their own dependencies MUST be declared as empty elements within the graph.
> Components or services that are not represented in the dependency graph MAY have unknown
> dependencies. It is RECOMMENDED that implementations assume this to be opaque and not an
> indicator of a object being dependency-free. It is RECOMMENDED to leverage compositions to
> indicate unknown dependency graphs.</xs:documentation>
2067c2069
< <xs:element name="expression" type="xs:normalizedString" minOccurs="0" maxOccurs="1">
---
> <xs:element name="expression" minOccurs="0" maxOccurs="1">
2071a2074,2087
> <xs:complexType>
> <xs:simpleContent>
> <xs:extension base="xs:normalizedString">
> <xs:attribute name="bom-ref" type="bom:refType">
> <xs:annotation>
> <xs:documentation>
> An optional identifier which can be used to reference the license elsewhere in the BOM.
> Uniqueness is enforced within all elements and children of the root-level bom element.
> </xs:documentation>
> </xs:annotation>
> </xs:attribute>
> </xs:extension>
> </xs:simpleContent>
> </xs:complexType>
2482c2498
< limited support. They provide the ability to preview a release prior to its general availability.
---
> limited support. They provide the ability to preview a release prior to its general availability.
2484c2500
< by the project or manufacturer that produced it.
---
> by the project or manufacturer that produced it.
2519c2535
< include unofficial terms used by development and marketing teams (e.g. code names).</xs:documentation>
---
> include unofficial terms used by development and marketing teams (e.g. code names).</xs:documentation>
2552c2568
< note elements may be specified to support release notes in a wide variety of languages.</xs:documentation>
---
> note elements may be specified to support release notes in a wide variety of languages.</xs:documentation>
2599,2604c2615,2620
< <!--
< Model card support in CycloneDX is derived from TensorFlow Model Card Toolkit released under the Apache 2.0 license and
< available from https://github.com/tensorflow/model-card-toolkit/blob/main/model_card_toolkit/schema/v0.0.2/model_card.schema.json.
< In addition, CycloneDX model card support includes portions of VerifyML, also released under the Apache 2.0 license and
< available from https://github.com/cylynx/verifyml/blob/main/verifyml/model_card_toolkit/schema/v0.0.4/model_card.schema.json.
< -->
---
> <!--
> Model card support in CycloneDX is derived from TensorFlow Model Card Toolkit released under the Apache 2.0 license and
> available from https://github.com/tensorflow/model-card-toolkit/blob/main/model_card_toolkit/schema/v0.0.2/model_card.schema.json.
> In addition, CycloneDX model card support includes portions of VerifyML, also released under the Apache 2.0 license and
> available from https://github.com/cylynx/verifyml/blob/main/verifyml/model_card_toolkit/schema/v0.0.4/model_card.schema.json.
> -->
3348c3364
< <xs:element name="id" type="xs:normalizedString" minOccurs="0" maxOccurs="1">
---
> <xs:element name="id" type="xs:normalizedString" minOccurs="1" maxOccurs="1">
3354c3370
< <xs:element name="source" type="bom:vulnerabilitySourceType" minOccurs="0" maxOccurs="1">
---
> <xs:element name="source" type="bom:vulnerabilitySourceType" minOccurs="1" maxOccurs="1">
3425,3427c3441,3443
< <xs:annotation>
< <xs:documentation>Precise steps to reproduce the vulnerability.</xs:documentation>
< </xs:annotation>
---
> <xs:annotation>
> <xs:documentation>Precise steps to reproduce the vulnerability.</xs:documentation>
> </xs:annotation>
3687c3703
< For example: https://nvd.nist.gov/vuln/detail/CVE-2021-39182</xs:documentation>
---
> For example: https://nvd.nist.gov/vuln/detail/CVE-2021-39182</xs:documentation>
3786c3802
<
---
>
5448c5464
< </xs:schema>
\ Pas de fin de ligne à la fin du fichier
---
> </xs:schema>
diff cyclonedx-go/schema/bom-1.6.xsd specification/schema/bom-1.6.xsd
27c27
< <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="spdx.xsd"/>
---
> <xs:import namespace="http://cyclonedx.org/schema/spdx" schemaLocation="http://cyclonedx.org/schema/spdx"/>
2421c2421
< object or an array of identity objects. Support for specifying identify as a single object was
---
> object or an array of identity objects. Support for specifying identity as a single object was
Suggestion: using a git submodule to reference github.com/CycloneDX/specification in the Java, Go and Python CycloneDX implementation
Using a git submodule would streamlined the JSON Schema and XSD files across all CycloneDX implementations.
This would also streamlined valid- and invalid- sample JSON and XML BOM files from CycloneDX/specification/tools/src/test/resources across the Java, Go and Python CycloneDX implementation, making unit tests easier to maintain over time and projects.
I still think this feature is a useful add-on to our schema files hosted on github.
I tried several IDEs lately, and tested capabilities of manually writing XML for certain schemas. For almost of them, I had to manually map schema to files. But I also learned, that they support XML catalogs for that job - which spared me the manually mapping. This was needed, when I was writing test cases for the not-yet-published CDX1.7 - which is not available via HTTP under the address that resembles the namespace.
Therefore, I consider this thing as a developer experience.
The schema catalog would not be hosted on the web, it stays in the repo with the files, and would be maintained by us.
@stevespringett , i highly support this feature, and I think we should adopt it. WDYT?
@Nicolas-Peiffer , thank you for providing this feature and the tests for it.