Dependency type definition in JSON Schema and XSD Schema are inconsistent

[ajbrown]

The way dependency objects are defined differs between the XSD and the JSON schema and documentation. The published documentation and JSON schema define "dependsOn" as a list of BOM ref strings, whereas the XSD defines the "dependsOn" list as a list of dependency objects, which would allow them to be nested.

The inconsistency causes confusing expectations across languages / systems, as some allow for nested dependencies and others do not.

Additionally, it appears that the XSD defines an element called "dependencies" whereas the JSON schema calls it "dependsOn"

XSD Definition

    <xs:complexType name="dependencyType">
        <xs:sequence minOccurs="0" maxOccurs="unbounded">
            <xs:element name="dependency" type="bom:dependencyType"/>
        </xs:sequence>
        <xs:attribute name="ref" type="bom:refType" use="required">
            <xs:annotation>
                <xs:documentation>References a component or service by the its bom-ref attribute</xs:documentation>
            </xs:annotation>
        </xs:attribute>
        <xs:anyAttribute namespace="##other" processContents="lax">
            <xs:annotation>
                <xs:documentation>User-defined attributes may be used on this element as long as they
                    do not have the same name as an existing attribute used by the schema.</xs:documentation>
            </xs:annotation>
        </xs:anyAttribute>
    </xs:complexType>

JSON Schema Definition

"dependency": {
      "type": "object",
      "title": "Dependency",
      "description": "Defines the direct dependencies of a component. 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.",
      "required": [
        "ref"
      ],
      "additionalProperties": false,
      "properties": {
        "ref": {
          "$ref": "#/definitions/refType",
          "title": "Reference",
          "description": "References a component by the components bom-ref attribute"
        },
        "dependsOn": {
          "type": "array",
          "uniqueItems": true,
          "additionalItems": false,
          "items": {
            "$ref": "#/definitions/refType"
          },
          "title": "Depends On",
          "description": "The bom-ref identifiers of the components that are dependencies of this dependency object."
        }
      }
    }

Documentation:

This stems from the issues raised in language libraries around nested dependencies:

• Java: Dependencies within Dependency class should be List<String> not List<Dependency> cyclonedx-core-java#199
• GoLang: Dependencies list in Dependency struct should be an array of String, not Dependency cyclonedx-go#36

[ajbrown]

Just as a note, it appears the field name difference is handled during (de)serialization by the 2 libraries I checked (Go, Java) so it seems there are no portability issues with that at the moment.

[madpah]

Good spot @ajbrown - I just came across this working on cyclonedx-python-lib.

@stevespringett / @coderpatros - can we consider aligning the schemas more here, unless there is a good reason to require the difference?