spdx-spec
spdx-spec copied to clipboard
spdx
Where should we display a serialized name of a property/class in the documentation?
Currently a TODO in Annex B: Getting started writing SPDX 3 (Informative)
https://github.com/spdx/spdx-spec/blob/aac3e38b0b01b2ccb129367617a07598cf0ccdd8/docs/annexes/getting-started.md?plain=1#L391-L392
Considerations (summary/elaborated from comments below):
- There should be a clear information about the serialized name to assist the SBOM authoring/checking by a human. As stated in the TODO.
- Serialized name in this case is specific to JSON-LD
- So while it can be handy but it may not be ideal to have the information in the main spec documentation, that meant to be generic/neutral to implementation.
- One option is to have the information in a page/section that specific to serialization (for example, 4 Model and serializations).
- In the case that it is to be included in the main spec doc, it has to be clear that this information is for a specific type of serialization. (What the labeling it should be?)
- Another design decision to made is, should it be necessary to 1) have a serialized name articulated for each element/property/etc (for clarity) or it is enough to 2) have just a short sentence to explain the format and let the SBOM author/practitioner figure the rest out by themselves (for brevity).
Proposed code are now available at repo/branches as shown in https://github.com/spdx/spec-parser/issues/132 but still need to decide where this serialized name should be displayed.
HTML pages generated from those two options are shown here for discussion, more options can be added:
- Display the serialized name just immediately after the name
- Display the serialized name inside the Metadata box
I don't believe this should be visible there.
It's part of the JSON-LD context, and it is relevant only for the JSON-LD serialization.
We could have a short sentence explaining its format in the serializations chapter.
I agree that it's only relevant in the JSON-LD context and not for other serialization options, so it can be a bit "intrusive" to include this information in the main doc (which meant to be generic/neutral).
But still believe that it should be generated and visible somewhere for easy reference, providing more confidence for the SBOM author when authoring/checking SBOM.
(Updated: Change the issue title to ask for comments. Update the issue description to include the considerations discussed)
During 2024-07-09 Tech team meeting, towards the very end in the context of an updated spec parser, there is a discussion about the availability of this serialized name. There's no conclusion yet. From the minutes:
- Is it possible to put the serialized JSON property in the table?
- Joshua thinks that this will help with confusion.
- Document of JSON-LD context needs to be somewhere.
- Writing a JSON-LD document from the page won't work.
- Alexios notes that the document describes RDF model.
