Where should we display a serialized name of a property/class in the documentation?

[bact]

Currently a TODO in Annex B: Getting started writing SPDX 3 (Informative)

spdx-spec/docs/annexes/getting-started.md

Lines 391 to 392 in aac3e38

	as that sets the prefix (the documentation should make it clear what the
	serialized name of a property is if you are unsure *TODO: It does not yet*).

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).

[bact]

Proposed code are now available at repo/branches as shown in spdx/spec-parser#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:

1. Display the serialized name just immediately after the name
   
   
   
2. Display the serialized name inside the Metadata box
   
   
   

[zvr]

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.

[bact]

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)

[bact]

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.

[goneall]

Per comment in SPDX minutes - moving this to post 3.0.1