specVersion has no restrictions on value

[douglasdennis]

The JSON schema has specVersion as a string with no restrictions on its value. This means that a BOM with any random string for a specVersion is valid, like:

{ "bomFormat": "CycloneDX", "specVersion": "foobar" }

Is this the intention? Should validation tools allow for random strings in the specVersion field? Or should they restrict to the known valid spec versions?

[jkowalleck]

Should validation tools allow for random strings in the specVersion field?

Yes, according to the spec, they MUST allow arbitrary strings for specVersion.

---

lets try the following

{ "bomFormat": "CycloneDX", "specVersion": "1.6",  "components": [{ 
  "type": "library",
  "name": "foo",
  "version": "v124",
  "modified": false 
}]}

this is valid for schema >= 1.2 < 2. regardless of the value in specVersion.

Let's say I have a tool supporting the entirety of CycloneDX 1.2 JSON. not 1.3 or later.
The JSON from above can be consumed by this tool, regardless of the specVersion

---

if this would be changed, then this would be a breaking change.

[douglasdennis]

I don't think that is a valid bom for 1.2 because you're missing the version field. Which I think illuminates the fact that, while y'all have clearly tried very hard to make BOMs be as resilient to schema changes as possible, there will still likely be differences enough between the versions that require validation tools to know what they are looking at.

Regardless, if you added a version, it won't pass this tools validation: https://cyclonedx.github.io/cyclonedx-web-tool When I put it in I got the message: Incorrect schema version: expected 1.2 actual 1.6 Which I think also demonstrates that the general expectation from a tool developer is that specVersion can be counted on.

I would propose a path forward: make the general guidance to validation tools be that they should only validate BOMs which contain a specVersion value that they recognize. This retains flexibility for folks to put whatever they want in the field but communicates that if you put something nonstandard in there then it is unlikely to be accepted.

Another path would be to allow for either a string (what we have now) or a number. If it is a number then it has to be a valid CycloneDX version number and if it is a string then it can be whatever.

[jkowalleck]

I don't think that is a valid bom for 1.2 because you're missing the version field. [...]

CycloneDX 1.2 JSON schema requires a $.version, true, but you probably forgot, that this field has a default value.
Therefore, my example stands.

[jkowalleck]

I would propose a path forward: make the general guidance to validation tools be that they should only validate BOMs which contain a specVersion value that they recognize. This retains flexibility for folks to put whatever they want in the field but communicates that if you put something nonstandard in there then it is unlikely to be accepted.

this sounds impractical.
If data adheres to a known CycloneDX schema, it is considered valid.

PS:
Tools should do proper schema validation, instead of reading arbitrary strings.
the specVersion is mere informational. it describes an intent.

[jkowalleck]

Another path would be to allow for either a string (what we have now) or a number. If it is a number then it has to be a valid CycloneDX version number and if it is a string then it can be whatever.

Numbers? this sounds impractical.
CycloneDX uses Semantic versioning - potentially there could be a version 1.33.7 -- not a number.

[jkowalleck]

@stevespringett we might have opportunity to improve our guides regarding this topic.

[douglasdennis]

I don't think that is a valid bom for 1.2 because you're missing the version field. [...]

CycloneDX 1.2 JSON schema requires a $.version, true, but you probably forgot, that this field has a default value. Therefore, my example stands.

I didn't forget about the default value. default is an annotation in json-schema and so is only there for informational purposes. required is a validation keyword and actually holds authority here. From https://json-schema.org/understanding-json-schema/reference/annotations: "The default keyword specifies a default value. This value is not used to fill in missing values during the validation process." I stand by that the example BOM is an invalid BOM for 1.2, if validated against the JSON Schema.

this sounds impractical.

I disagree.

If data adheres to a known CycloneDX schema, it is considered valid.

I'm concerned about the implications of this. What if the semantics of a field changes between versions? How do I know that my understandings of what a field means are in agreement with the data if I don't have some way of validating that our understanding of a field comes from the same governing document? If a schema was just the fields and data types then why have descriptions?

Numbers? this sounds impractical.
CycloneDX uses Semantic versioning - potentially there could be a version 1.33.7 -- not a number.

Fair. I didn't realize CycloneDX versions might have a patch number.

we might have opportunity to improve our guides regarding this topic.

I would also suggest that it would be nice if there was a formally adopted reference implementation of a CycloneDX validator and it was pointed to by the documentation.

[prabhu]

Related: #438