[3.1-RC1] Fill in stub class/property pages with prose and examples before RC2

[henrylyons]

Affected Sections: model/

Feedback
Several class and property pages are stub-level; human implementers need authoritative class-by-class prose with examples.

Suggested Change:
Fill these in before RC2. Microsoft is willing to contribute examples for Software, Build, and Security. (model/)

Notes:
This feedback was provided by Microsoft at the SPDX working group meeting on June 30, 2026.

[goneall]

Should we put examples in the text?

We're getting feedback that we need examples easily accessible - ideally on the actual website.

Concern about including the examples in the ISO version.

We could separate out the examples and only publish the examples to the website and not the ISO document.

Need to have rules about where the examples are.

We could have a markdown tag in the model files. Alternatively, we could have the examples in a separate location and have the spec parser merge it in.

We could create a shadow structure where we could add snippets that get merged in.

A separate directory in the model repo "example". Naming structure would mirror the model. If there's a markdown file with an example, it gets pulled in during the spec parsers.

File names will be exactly the same, any markdown will do - should be in JSON-LD format. Will get merged into the published webpage.

Examples should be JSON-LD.

We should have a CI that validates the examples.

TODO:
Setup the directory as a PR - Gary
Copy the security examples to the separate directory - Gary will do a first one, Alexios and Arthit - will help with others
Populate some examples - @henrylyons - once the directory is in place, feel free to start adding
Update the spec-parser (make sure it works for both 3.0 and 3.1 spec versions) - Alexios
Create a CI to validate - Joshua, Arthit
Optionally, autogenerate some example snippet files (Gary to look at later)