Ontology documentation and content negotiation

[VladimirAlexiev]

Continuing #1163:
Ontology and term URLs should support content negotiation and return human or machine readable info

• by default, they should return HTML
  • Where is the ontology documentation?
  • I know that you generate the ointology from markdown (congratulations!) so I thought there would be some nice ref doc generated
  • but https://spdx.dev/learn/areas-of-interest/software/ points to
    https://github.com/spdx/spdx-3-model/tree/main/model/Software which has to be navigated manually to eg to to
    https://github.com/spdx/spdx-3-model/blob/main/model/Software/Classes/Package.md... not very convenient
  • There are a number of ontology ref doc generators. LODE and PyLODE are perhaps most popular
  • These generate anchors for each term. Please ensure that each term URL redirects to the appropriate anchor
• they should also return Turtle (accept: text/turtle)
• maybe you'd also want to return JSON-LD (accept: application/ld+json). I can help with nice formatting of ontologies as JSONLD.

[zvr]

Yes, this is a known TO-DO item.

We used to have it the ontology generated on SPDXv2 (still accessible at https://spdx.org/rdf/terms/); we haven't yet implemented it for SPDXv3.

A further complication is that there is currently no server to implement the content negotiation (AFAIK), so this will require a restructuring of our architecture.

[VladimirAlexiev]

I now found the rendered documentation

• Eg https://spdx.github.io/spdx-spec/v3.0.1/model/Extension/Properties/cdxProperty/
• I think that is fine, though some people will prefer a single-page doc
• but the FTS is not very good, I'll post an issue

If you decide to use documentation generated from the ontology:

• The LODE version that you used has a couple defects:
  • doesn't render markdown (I don't know whether you use markdown in term descriptions, but I see a couple bullets in the ontology record that are not rendered)
  • doesn't have a Table of Contents
• Let's try PyLODE

[bact]

This is how SPDX 3 spec in the model part is currently written, based on Markdown format:

• https://github.com/spdx/spdx-3-model/blob/develop/README.md#formats
• https://github.com/spdx/spdx-3-model/blob/develop/docs/format.md

The spec website is generated using this workflow:

• https://github.com/spdx/spdx-spec/blob/develop/build.md

[bact]

We can do the 303 See Other redirection as suggested by these W3C best practices documents:

• Cool URIs for the Semantic Web https://www.w3.org/TR/cooluris/
• Best Practice Recipes for Publishing RDF Vocabularies https://www.w3.org/TR/swbp-vocab-pub/

But that likely need more than a simple redirection that AWS S3 supported. An HTTP server or at least a cloud function ("serverless function", like AWS Lambda, Cloudflare Workers, Netify Functions, Vercel, etc) is needed to check the Accept header.

(just checked, AWS Lambda Free Tier gets 1 million free request per month.)

[bact]

We can have the work items about this in https://github.com/spdx/infrastructure - but don't lost the -rc2 track.

For documentation about the content negotiation, it should be in this spec repo - some of it can be in the annex of the spec (informative).