Update ratings descriptions in schema files for clarity on VEX usage

[fahedouch]

I am translating @stevespringett 's feedback on the CycloneDX VEX specification into the code.

Should ratings be normative inputs for prioritization in VEX consumers?

Yes, they should be. It is widely known that the NVD has historically overrated vulnerabilities (on purpose). So the ratings from the NVD and those from the manufactures are often different. CycloneDX can convey this information which can aid in prioritization.

fixes #719

[fahedouch]

@stevespringett please take a look!

[stevespringett]

I'm fine with these changes. @jkowalleck thoughts? We'll also need to make the same changes to the XML and protobuf schemas as well.

Additionally, you can remove the changes to the vulnerability extension. That hasn't been supported for many years.

[fahedouch]

@stevespringett thank you for your feedback. fixed.

[Copilot]

Pull request overview

This pull request updates the documentation for the ratings field in vulnerability objects across CycloneDX schema files to provide normative guidance on their usage in VEX (Vulnerability Exploitability eXchange) contexts. Based on feedback from issue #719, the changes clarify that vulnerability ratings should be treated as actionable inputs for prioritization decisions by VEX consumers.

Changes:

• Adds RFC 2119 normative language (SHOULD/SHOULD NOT) to the ratings field documentation across schema versions 1.6 and 1.7
• Updates documentation in XSD, JSON Schema, and Protocol Buffer formats for consistency
• Emphasizes that ratings from different sources may differ and aid in vulnerability prioritization

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
schema/bom-1.7.xsd	Updated vulnerability ratings documentation to include guidance for VEX consumers
schema/bom-1.7.schema.json	Updated vulnerability ratings description with normative language
schema/bom-1.7.proto	Updated ratings comment to match normative guidance
schema/bom-1.6.xsd	Updated vulnerability ratings documentation for version 1.6 compatibility
schema/bom-1.6.schema.json	Updated vulnerability ratings description in JSON schema
schema/bom-1.6.proto	Updated ratings comment in Protocol Buffer schema

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[fahedouch]

thanks @copilot for review. I reflected @copilot comments.

new phrase is:

List of vulnerability ratings. Consumers SHOULD consider ratings in prioritization decisions; source ratings may differ and aid prioritization.

aid prioritization is preferable to provide valuable context for the following reasons:

It's more actionable - developers understand exactly why it matters
It's more transparent - if the true purpose is to assist with prioritization, it should be stated explicitly
It reinforces the message - it maintains consistency with "in prioritization decisions" in the first clause

@jkowalleck @stevespringett PTAL

[jkowalleck]

LGTM

[stevespringett]

Thank you for the PR and appologies for the delay. I noticed the JSON schemas have a different description than the XSD and Protobuf. Can you update the JSON schema description to match that of the XSD and Protobuf please.

The description should read:

List of vulnerability ratings. Consumers SHOULD consider ratings in prioritization decisions; source ratings may differ and aid prioritization.

[fahedouch]

Thank you for the PR and appologies for the delay. I noticed the JSON schemas have a different description than the XSD and Protobuf. Can you update the JSON schema description to match that of the XSD and Protobuf please.

The description should read:

List of vulnerability ratings. Consumers SHOULD consider ratings in prioritization decisions; source ratings may differ and aid prioritization.

no worries. Fixed :)