Skip to content

[WIP] docs: streamline descriptions - literals, references, code #1084

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
jkowalleck wants to merge 2 commits into
base: 2.0-dev
Choose a base branch
from
Draft

[WIP] docs: streamline descriptions - literals, references, code #1084

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2ab6b6b
docs: streamline descriptions - literals, references, code
jkowalleck Sep 8, 2026
6f6f532
docs: streamline descriptions - literals, references, code
jkowalleck Sep 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions schema/2.0/cyclonedx-2.0.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
"specFormat": {
"type": "string",
"title": "Specification Format",
"description": "Specifies the format. This value shall be \"CycloneDX\".",
"description": "Specifies the format. This value shall be `\"CycloneDX\"`.",
"enum": [
"CycloneDX"
]
Expand All @@ -43,7 +43,7 @@
"version": {
"type": "integer",
"title": "BOM Version",
"description": "Whenever an existing BOM is modified, either manually or through automated processes, the version of the BOM SHOULD be incremented by 1. When a system is presented with multiple BOMs with identical serial numbers, the system SHOULD use the most recent version of the BOM. The default version is '1'.",
"description": "Whenever an existing BOM is modified, either manually or through automated processes, the version of the BOM SHOULD be incremented by 1. When a system is presented with multiple BOMs with identical serial numbers, the system SHOULD use the most recent version of the BOM. The default version is `1`.",
"minimum": 1,
"default": 1
},
Expand All @@ -52,7 +52,7 @@
},
"components": {
"$ref": "model/cyclonedx-component-2.0.schema.json#/$defs/components",
"description": "A collection of components. When a metadata component is present, this array represents the inventory of components associated with that subject, forming a bill of materials. When the metadata component is omitted, the array provides component data for interchange purposes without establishing a compositional relationship."
"description": "A collection of components. When a metadata component is present, this array represents the inventory of components associated with that subject, forming a bill of materials. When the `metadata.component` is omitted, the array provides component data for interchange purposes without establishing a compositional relationship."
},
"dependencies": {
"$ref": "model/cyclonedx-dependency-2.0.schema.json#/$defs/dependencies"
Expand Down
2 changes: 1 addition & 1 deletion schema/2.0/model/cyclonedx-ai-modelcard-2.0.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"$comment": "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.",
"type": "object",
"title": "Model Card",
"description": "A model card describes the intended uses of a machine learning model and potential limitations, including biases and ethical considerations. Model cards typically contain the training parameters, which datasets were used to train the model, performance metrics, and other relevant data useful for ML transparency. This object SHOULD be specified for any component of type `machine-learning-model` and must not be specified for other component types.",
"description": "A model card describes the intended uses of a machine learning model and potential limitations, including biases and ethical considerations. Model cards typically contain the training parameters, which datasets were used to train the model, performance metrics, and other relevant data useful for ML transparency. This object SHOULD be specified for any component with `type=\"machine-learning-model\"` and must not be specified for other component types.",
"additionalProperties": false,
"properties": {
"bom-ref": {
Expand Down
10 changes: 5 additions & 5 deletions schema/2.0/model/cyclonedx-behavior-2.0.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -266,7 +266,7 @@
],
"meta:enum": {
"activity": "An action that is performed, identified by a behavior, a behavior-instance reference, or a nested graph. The activity-flow counterpart of a step.",
"state": "A durable condition the subject rests in until a transition fires. The state-machine counterpart of a node. A composite state references its nested region through 'graph'.",
"state": "A durable condition the subject rests in until a transition fires. The state-machine counterpart of a node. A composite state references its nested region through `graph`.",
"event": "An intermediate event that occurs during the graph.",
"gateway": "A branch or merge point whose outgoing transitions carry the guards.",
"initial": "The starting point of the graph or of a composite node.",
Expand All @@ -287,22 +287,22 @@
"type": "integer",
"title": "Ordinal",
"minimum": 1,
"description": "Position within a sequential graph. Required when the graph ordering is 'sequential'. Ignored when transitions define the order."
"description": "Position within a sequential graph. Required when the graph's `ordering=\"sequential\"`. Ignored when transitions define the order."
},
"behavior": {
"$ref": "../../behavior-taxonomy.schema.json",
"title": "Behavior",
"description": "For an activity node, the behavior performed, drawn from the taxonomy. Mutually exclusive with 'ref' and 'graph'."
"description": "For an activity node, the behavior performed, drawn from the taxonomy. Mutually exclusive with `ref` and `graph`."
},
"ref": {
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType",
"title": "Behavior Reference",
"description": "For an activity node, a reference to a behavior instance. Mutually exclusive with 'behavior' and 'graph'."
"description": "For an activity node, a reference to a behavior instance. Mutually exclusive with `behavior` and `graph`."
},
"graph": {
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType",
"title": "Graph Reference",
"description": "A reference to a nested behavior graph. For an activity node it is the sub-process performed and is mutually exclusive with 'behavior' and 'ref'; for a composite node it is the nested region."
"description": "A reference to a nested behavior graph. For an activity node it is the sub-process performed and is mutually exclusive with `behavior` and `ref`; for a composite node it is the nested region."
},
"actors": {
"type": "array",
Expand Down
18 changes: 9 additions & 9 deletions schema/2.0/model/cyclonedx-blueprint-2.0.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -283,11 +283,11 @@
"items": {
"$ref": "cyclonedx-party-2.0.schema.json#/$defs/partyChoice"
},
"description": "The parties that created the blueprint. Each entry is either an inline party object or a reference to a previously declared party. The party's `roles` should include `author`."
"description": "The parties that created the blueprint. Each entry is either an inline party object or a reference to a previously declared party. The party's `roles` should include `\"author\"`."
},
"reviewer": {
"$ref": "cyclonedx-party-2.0.schema.json#/$defs/partyChoice",
"description": "The party that reviewed the blueprint. The party's `roles` should include `reviewer`."
"description": "The party that reviewed the blueprint. The party's `roles` should include `\"reviewer\"`."
},
"reviewDate": {
"type": "string",
Expand All @@ -297,7 +297,7 @@
},
"approver": {
"$ref": "cyclonedx-party-2.0.schema.json#/$defs/partyChoice",
"description": "The party that approved the blueprint. The party's `roles` should include `signatory` or a custom role identifying the approving authority."
"description": "The party that approved the blueprint. The party's `roles` should include `\"signatory\"` or a custom role identifying the approving authority."
},
"approvalDate": {
"type": "string",
Expand Down Expand Up @@ -338,7 +338,7 @@
"type": "string",
"title": "Review Frequency",
"pattern": "^P(?!$)(\\d+Y)?(\\d+M)?(\\d+W)?(\\d+D)?$",
"description": "ISO 8601 duration for review frequency (e.g., P3M for quarterly)."
"description": "ISO 8601 duration for review frequency (e.g., `\"P3M\"` for quarterly)."
}
}
},
Expand Down Expand Up @@ -410,7 +410,7 @@
},
"componentRef": {
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType",
"description": "Reference using bom-link or bom-ref to the component this asset represents, including components of type `service`."
"description": "Reference using bom-link or bom-ref to the component this asset represents, including components of type `\"service\"`."
},
"partyRef": {
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType",
Expand Down Expand Up @@ -844,7 +844,7 @@
"items": {
"$ref": "cyclonedx-party-2.0.schema.json#/$defs/partyChoice"
},
"description": "Parties that own the dataset. Each entry is either an inline party object or a reference to a previously declared party. The party's `roles` should include `owner`."
"description": "Parties that own the dataset. Each entry is either an inline party object or a reference to a previously declared party. The party's `roles` should include `\"owner\"`."
},
"authorization": {
"type": "array",
Expand Down Expand Up @@ -967,7 +967,7 @@
},
"dataFormat": {
"type": "string",
"description": "Data format (e.g., JSON, XML, Protocol Buffers)."
"description": "Data format (e.g., `\"JSON\"`, `\"XML\"`, `\"Protocol Buffers\"`)."
},
"authentication": {
"type": "array",
Expand Down Expand Up @@ -1727,7 +1727,7 @@
},
"owner": {
"$ref": "cyclonedx-party-2.0.schema.json#/$defs/partyChoice",
"description": "The party responsible for tracking, validating, and maintaining this assumption over the lifecycle of the model. May be an inline party object or a reference to a previously declared party. The party's `roles` should include `owner`."
"description": "The party responsible for tracking, validating, and maintaining this assumption over the lifecycle of the model. May be an inline party object or a reference to a previously declared party. The party's `roles` should include `\"owner\"`."
},
"validationMethod": {
"type": "string",
Expand Down Expand Up @@ -1943,7 +1943,7 @@
"ownership": {
"type": "array",
"title": "Ownership",
"description": "Parties responsible for the asset. Each entry is either an inline party object or a reference to a previously declared party. The party's `roles` carry the relationship (`owner`, `steward`, `custodian`, `end-user`, or a custom role). Multiple parties may share the same role; preference among them is expressed via `role.order`.",
"description": "Parties responsible for the asset. Each entry is either an inline party object or a reference to a previously declared party. The party's `roles` carry the relationship (`\"owner\"`, `\"steward\"`, `\"custodian\"`, `\"end-user\"`, or a custom role). Multiple parties may share the same role; preference among them is expressed via `role.order`.",
"uniqueItems": true,
"items": {
"$ref": "cyclonedx-party-2.0.schema.json#/$defs/partyChoice"
Expand Down
2 changes: 1 addition & 1 deletion schema/2.0/model/cyclonedx-certification-2.0.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@
"jurisdiction": {
"type": "string",
"title": "Jurisdiction",
"description": "ISO 3166-1 alpha-2 country code, ISO 3166-2 subdivision, or supranational identifier such as `EU`, where the certification applies.",
"description": "ISO 3166-1 alpha-2 country code, ISO 3166-2 subdivision, or supranational identifier such as `\"EU\"`, where the certification applies.",
"examples": [ "US", "EU", "GB", "AU", "US-CA" ]
},
"level": {
Expand Down
8 changes: 4 additions & 4 deletions schema/2.0/model/cyclonedx-citation-2.0.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@
},
"minItems": 1,
"title": "Field References",
"description": "One or more [JSON Pointers](https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM fields to which the attribution applies.\nExactly one of the \"pointers\" or \"expressions\" elements must be present."
"description": "One or more [JSON Pointers](https://datatracker.ietf.org/doc/html/rfc6901) identifying the BOM fields to which the attribution applies.\nExactly one of the `pointers` or `expressions` elements must be present."
},
"expressions": {
"type": "array",
Expand All @@ -42,7 +42,7 @@
},
"minItems": 1,
"title": "Path Expressions",
"description": "One or more path expressions used to locate values within a BOM.\nExactly one of the \"pointers\" or \"expressions\" elements must be present."
"description": "One or more path expressions used to locate values within a BOM.\nExactly one of the `pointers` or `expressions` elements must be present."
},
"timestamp": {
"type": "string",
Expand All @@ -53,12 +53,12 @@
"attributedTo": {
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType",
"title": "Attributed To",
"description": "The `bom-ref` of an object, such as a component, service, tool, organisational entity, or person that supplied the cited information.\nAt least one of the \"attributedTo\" or \"process\" elements must be present."
"description": "The `bom-ref` of an object, such as a component, service, tool, organisational entity, or person that supplied the cited information.\nAt least one of the `attributedTo` or `process` elements must be present."
},
"process": {
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType",
"title": "Process Reference",
"description": "The `bom-ref` to a process (such as a formula, workflow, task, or step) defined in the `formulation` section that executed or generated the attributed data.\nAt least one of the \"attributedTo\" or \"process\" elements must be present."
"description": "The `bom-ref` to a process (such as a formula, workflow, task, or step) defined in the `formulation` section that executed or generated the attributed data.\nAt least one of the `attributedTo` or `process` elements must be present."
},
"note": {
"type": "string",
Expand Down
Loading
Loading