CycloneDX / CycloneDX/specification
[2.0] docs - streamline code, literals, in-text examples, referenced properties
- Dominant language
- XSLT
- Stars
- 547
- Forks
- 93
- Avg merge
- 7h 11m
- Merged PRs (30d)
- 37
Description
in the CycloneDX 2.0 documentationals `description`, `$comment`, `meta:enum` there are string literals, references to properties, and other "special elements" used, that shall be given some semantics - and they need streamlining.
in the JSON files, search for regex:
```text
\\"|'|`
```
examples
- https://github.com/CycloneDX/specification/blob/a1c8aeb2e4e6a72851fd937f210e9b5add1cf514/schema/2.0/model/cyclonedx-ai-modelcard-2.0.schema.json#L12
here the string `machine-learning-model` refers to a specific string literal which shall be used for the field `type` of a component.
- https://github.com/CycloneDX/specification/blob/a1c8aeb2e4e6a72851fd937f210e9b5add1cf514/schema/2.0/model/cyclonedx-behavior-2.0.schema.json#L295
here the `ref` and `graph` are referring to other fields in the object.
- and so on ...
goal:
- Referred fields are markdown code blocks -- start and stop with a "\`"
- string literal values are marked as such by using double quotes -- like `"some_value"`
- if a value refers to a property, then the code blocks hall make this clear -- `myField="some_value"` or `myOther=false`
example fixes:
```patch
- "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.",
```
```patch
- "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`."
```
Contributor guide
Assessment
This issue has not been assessed yet.