[FEATURE] xml catalog for XSD

[Nicolas-Peiffer]

Adding an XML catalog file and corresponding Java unit tests to validate the XML catalog content match local XSD file content.

Please see also: #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)

[stevespringett]

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?

[Nicolas-Peiffer]

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/schema perhaps?

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.