CycloneDX / CycloneDX/specification

[2.0] docs - streamline code, literals, in-text examples, referenced properties

Open
#1,085 0 comments 0 reactions 1 assignee Claimed by @jkowalleck View on GitHub
CDX 2.0 documentation
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.