docs: streamline descriptions - literals, references, code - #1084
Open
jkowalleck wants to merge 8 commits into
Open
docs: streamline descriptions - literals, references, code#1084jkowalleck wants to merge 8 commits into
jkowalleck wants to merge 8 commits into
Conversation
jkowalleck
changed the title
jkowalleck
force-pushed
the
2.0-dev_fix_descritions-literals-code
branch
2 times, most recently
from
September 7, 2026 21:11
a1d0203 to
6f6f532
Compare
Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com>
jkowalleck
changed the title
jkowalleck
marked this pull request as ready for review
September 9, 2026 12:43
jkowalleck
requested review from
DarthHater,
coderpatros,
mrutkows and
stevespringett
and
a lite review from Copilot
September 9, 2026 12:43
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Multiple updated descriptions introduce broken/mismatched quoting/backticks (and one misleading property reference), which will render incorrectly and reduce documentation clarity.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR updates CycloneDX 2.0 JSON Schema documentation strings to consistently distinguish (a) referenced properties and (b) string literal values, aligning with the conventions discussed in issue #1085.
Changes:
- Standardizes in-text references to properties using inline code spans (backticks).
- Marks string literal enum/examples using quoted literals (e.g.,
"value") inside inline code spans where appropriate. - Streamlines various descriptions, comments, and examples across the 2.0 schema model files.
File summaries
| File | Description |
|---|---|
| schema/2.0/model/cyclonedx-vulnerability-2.0.schema.json | Updates vulnerability documentation strings, including references to analysis state values. |
| schema/2.0/model/cyclonedx-usecase-2.0.schema.json | Standardizes examples and inline literal formatting in use-case descriptions. |
| schema/2.0/model/cyclonedx-threat-2.0.schema.json | Standardizes property references and literal formatting in threat model descriptions. |
| schema/2.0/model/cyclonedx-risk-2.0.schema.json | Standardizes literals/property references across risk rating documentation. |
| schema/2.0/model/cyclonedx-requirement-2.0.schema.json | Updates example formatting for requirement identifiers. |
| schema/2.0/model/cyclonedx-release-notes-2.0.schema.json | Updates release-type and locale example formatting in descriptions. |
| schema/2.0/model/cyclonedx-physical-2.0.schema.json | Standardizes literal formatting for physical classification and designator examples. |
| schema/2.0/model/cyclonedx-perspective-2.0.schema.json | Standardizes numeric literal formatting in descriptions. |
| schema/2.0/model/cyclonedx-patent-2.0.schema.json | Standardizes patent number examples as quoted literals. |
| schema/2.0/model/cyclonedx-party-2.0.schema.json | Standardizes role/order and label examples and inline property references. |
| schema/2.0/model/cyclonedx-metadata-2.0.schema.json | Standardizes property references and default literal formatting. |
| schema/2.0/model/cyclonedx-license-2.0.schema.json | Standardizes references to externalReference/type and evidence property paths. |
| schema/2.0/model/cyclonedx-jss_X590_2023_10-2.0.schema.json | Standardizes literal and property references in timestamp/signature documentation. |
| schema/2.0/model/cyclonedx-formulation-2.0.schema.json | Streamlines example phrasing while preserving code-span references. |
| schema/2.0/model/cyclonedx-evidence-2.0.schema.json | Standardizes numeric and string literal examples in evidence descriptions. |
| schema/2.0/model/cyclonedx-declaration-2.0.schema.json | Standardizes numeric literals in score/confidence descriptions. |
| schema/2.0/model/cyclonedx-data-2.0.schema.json | Standardizes MIME-type/literal examples and role literal formatting. |
| schema/2.0/model/cyclonedx-cryptography-2.0.schema.json | Standardizes literal examples and assetType-based property references. |
| schema/2.0/model/cyclonedx-control-2.0.schema.json | Standardizes numeric literal formatting in effectiveness descriptions. |
| schema/2.0/model/cyclonedx-composition-2.0.schema.json | Standardizes quoted-literal usage in enum documentation. |
| schema/2.0/model/cyclonedx-component-2.0.schema.json | Standardizes type/scope/version requirement wording and inline references. |
| schema/2.0/model/cyclonedx-common-2.0.schema.json | Standardizes literals/property references in common definitions and comments. |
| schema/2.0/model/cyclonedx-citation-2.0.schema.json | Standardizes property-name references for citation pointer/expression rules. |
| schema/2.0/model/cyclonedx-certification-2.0.schema.json | Standardizes example literal formatting (e.g., "EU"). |
| schema/2.0/model/cyclonedx-blueprint-2.0.schema.json | Standardizes role literals and example value formatting across blueprint docs. |
| schema/2.0/model/cyclonedx-behavior-2.0.schema.json | Standardizes property references and ordering/literal formatting in behavior docs. |
| schema/2.0/model/cyclonedx-ai-modelcard-2.0.schema.json | Updates model-card applicability wording using type="machine-learning-model". |
| schema/2.0/cyclonedx-2.0.schema.json | Standardizes top-level schema literal formatting and property references. |
Review details
Suppressed comments (2)
schema/2.0/model/cyclonedx-component-2.0.schema.json:314
- This requirement description has a dangling backtick and quotes around identifiers, which breaks the inline-code formatting and makes the condition harder to read.
"description": "Requirement: 'versionRange' must not be present when 'isExternal=false`.",
schema/2.0/model/cyclonedx-component-2.0.schema.json:811
- There is a mismatched quote in the inline code span (
type=\"data\"'), which breaks formatting; it should be a consistent property/value reference.
"description": "The bom-ref of the configuration that determines this component's configuration. Typically points to a component with `type=\"data\"' whose `data.type=\"configuration\"`."
- Files reviewed: 28/28 changed files
- Comments generated: 8
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Remaining unstandardized descriptions, stale generated bundles, and documentation defects prevent a complete, consistent update.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
Suppressed comments (2)
schema/2.0/model/cyclonedx-license-2.0.schema.json:152
- The rewrite introduces the grammatically incorrect article “a” before
externalReference; use “an” here.
"description": "The URL to the license file. If specified, a `externalReference` with `type=\"license\"` should also be specified for completeness",
schema/2.0/model/cyclonedx-cryptography-2.0.schema.json:99
- This changes the exact referenced filename into a quoted, unofficial schema name. The
$refimmediately above targetscryptography-defs.schema.json, and that file’s$iduses the same filename; retain that code-formatted identifier so readers can identify the referenced schema precisely.
"description": "The specific underlying Elliptic Curve (EC) definition employed which is an indicator of the level of security strength, performance and complexity. If specified, this value shall be one of the enumeration of valid elliptic curves identifiers defined in the \"cryptography-defs\" schema."
- Files reviewed: 28/28 changed files
- Comments generated: 5
- Review effort level: Balanced
| "type": "object", | ||
| "title": "Extensible Properties", | ||
| "$comment": "This is a mixin. It intentionally does NOT restrict additional/unevaluated properties itself; schemas composing it via `allOf` are expected to close themselves with `unevaluatedProperties: false` so that both their own defined properties and these patternProperties remain usable.", | ||
| "$comment": "This is a mixin. It intentionally does NOT restrict additional/unevaluated properties itself; schemas composing it via `allOf` are expected to close themselves with `unevaluatedProperties=false` so that both their own defined properties and these patternProperties remain usable.", |
| "$defs": { | ||
| "refType": { | ||
| "description": "Identifier for referable and therefore interlinkable elements.\nValue shall not start with the BOM-Link intro 'urn:cdx:' to avoid conflicts with BOM-Links.", | ||
| "description": "Identifier for referable and therefore interlinkable elements.\nValue shall not start with the BOM-Link intro `\"urn:cdx:\"` to avoid conflicts with BOM-Links.", |
| "$ref": "#/$defs/versionRange", | ||
| "title": "Component Version Range", | ||
| "description": "For an external component, this specifies the accepted version range.\nThe value must adhere to the Package URL Version Range syntax (vers), as defined at <https://github.com/package-url/vers-spec\nMay only be used if `.isExternal` is set to `true`.\nMust be used exclusively, either 'version' or 'versionRange', but not both." | ||
| "description": "For an external component, this specifies the accepted version range.\nThe value must adhere to the Package URL Version Range syntax (vers), as defined at <https://github.com/package-url/vers-spec\nMay only be used if `isExternal=true`.\nMust be used exclusively, either `version` or `versionRange`, but not both." |
| "$ref": "../../cryptography-defs.schema.json#/definitions/algorithmFamiliesEnum", | ||
| "title": "Algorithm Family", | ||
| "description": "A valid algorithm family identifier. If specified, this value shall be one of the enumeration of valid algorithm Family identifiers defined in the `cryptography-defs.schema.json` subschema.", | ||
| "description": "A valid algorithm family identifier. If specified, this value shall be one of the enumeration of valid algorithm Family identifiers defined in the \"cryptography-defs\" schema.", |
| "type": "string", | ||
| "title": "License URL", | ||
| "description": "The URL to the license file. If specified, a 'license' externalReference should also be specified for completeness", | ||
| "description": "The URL to the license file. If specified, a `externalReference` with `type=\"license\"` should also be specified for completeness", |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
revisited/streamlined all description and documentation