[2.0] docs - streamline code, literals, in-text examples, referenced properties
Assessment
This issue has not been assessed yet.
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:
\\"|'|`
examples
- https://github.com/CycloneDX/specification/blob/a1c8aeb2e4e6a72851fd937f210e9b5add1cf514/schema/2.0/model/cyclonedx-ai-modelcard-2.0.schema.json#L12
here the stringmachine-learning-modelrefers to a specific string literal which shall be used for the fieldtypeof a component. - https://github.com/CycloneDX/specification/blob/a1c8aeb2e4e6a72851fd937f210e9b5add1cf514/schema/2.0/model/cyclonedx-behavior-2.0.schema.json#L295
here therefandgraphare 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"ormyOther=false
example fixes:
- "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.",
- "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`."
- Dominant language
- XSLT
- Stars
- 551
- Forks
- 93
- Avg merge
- 4h 51m
- Merged PRs (30d)
- 42
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from CycloneDX/specification
-
Response vs Responce Open
Difficulty 1/5 Under an hour Newbie friendliness 68/100
CycloneDX/specification#1121 ·
-
defect documentation
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
CycloneDX/specification#1115 ·
-
cap: cryptography-registry
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
CycloneDX/specification#1098 ·
-
defect
Difficulty 1/5 Under an hour Newbie friendliness 91/100
CycloneDX/specification#1045 · 2 comments ·
-
CDX 2.0 documentation ready for review
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
CycloneDX/specification#1035 ·