JSON-LD Serialization doc: Fix relationship type name, Add validation info

[bact]

• In serialization/README.md
  • Remove serialization information section, as it is already at https://github.com/spdx/spdx-spec/blob/development/v3.0.1/docs/serializations.md
  • Sort/categorize use cases/serialization examples list
  • Fix name ExternalReference -> ExternalRef
• In serialization/jsonld.md:
  • Update IRIs to 3.0.1
  • In Validation section, add link to serialization/jsonld/validation.md
  • Add Examples section and add link to serialization/jsonld/examples.md
• Rename serialization/json_ld/ directory and serialization/json-ld.md to jsonld
  • For consistency with jsonld in spdx-spec and license-list-data repos
• Make heading capitalization consistent across directory

This is a rework of #766

[goneall]

LGTM

[goneall]

@rnjudge On line 74 of the README, there is a FIXME placeholder for external reference types for security.

Can you list which external references should be added?

Here's a link to the vocab: https://github.com/spdx/spdx-3-model/blob/main/model/Core/Vocabularies/ExternalRefType.md

[bact]

I cannot find spdxDocumentForArtfact (or spdxDocumentForArtifact) relationship type mentioned here:

A Relationship of type spdxDocumentForArtfact can be used to relate an SpdxDocument to one more serialized for of the SpdxDocument.

From #542, I believe it should be serializedInArtifact:

A Relationship of type serializedInArtifact can be used to relate an SpdxDocument to one more serialized for of the SpdxDocument.

My apology to tag people from #542
@goneall @JPEWdev @sbarnum @zvr can you please confirm this? Thank you.

This is related to 3.0.1 Model because I will copy this info, and one related to NamescapeMap in the next paragraph, to the Models and serializations chapter in the spec. So we can use the web page URL https://spdx.github.io/spdx-spec/v3.0.1/serializations/ (and not the repo URL) as a ref inside NamespaceMap description. (see TODOs from 30 July 2024 tech call at #796 (comment) )

--

I have put together as a first try the paragraphs in this PR spdx/spdx-spec#1016 - surely need a lot of edits, please kindly review there.

[bact]

Also this one on "XCollection"

When serializing the physical SpdxDocument, any properties of the logical element which can be represented using native mechanisms in the specific serialization format (e.g. @context prefixes in JSON-LD in place of the namespaceMap) should use these mechanisms and the remaining properties should be serialized within the “XCollection” element itself.

What is "XCollection" ?

[JPEWdev]

Also this one on "XCollection"

When serializing the physical SpdxDocument, any properties of the logical element which can be represented using native mechanisms in the specific serialization format (e.g. @context prefixes in JSON-LD in place of the namespaceMap) should use these mechanisms and the remaining properties should be serialized within the “XCollection” element itself.

What is "XCollection" ?

I believe it was the placeholder name for SpdxDocument, and the find/replace missed this one. It should be SpdxDocument

[bact]

What is "XCollection" ?

I believe it was the placeholder name for SpdxDocument, and the find/replace missed this one. It should be SpdxDocument

Thank you Joshua. I have replaced XCollection with SpdxDocument here and in the spec doc.

[bact]

Because the merge of spdx/spdx-spec#1016, now the Model and serializations chapter in the spec has the content from serialization/README.md's Serialization information section.

I will remove that content from the file here, leaving only the link to the spec.

[goneall]

@bact - could please resolve the merge conflicts - once completed, we can merge

[kestewart]

Looks good, but could please resolve the conflict, so we can merge.

[bact]

Thank you. @goneall @kestewart conflicts resolved.