Linkable terms

[nissimsan]

FYI:
w3c-ccg/traceability-vocab#531

Tagging @VladimirAlexiev

[HenrikHL]

Hi @nissimsan - do you expect anything from me?

[VladimirAlexiev]

My comment is that <https://api.swaggerhub.com/domains/dcsaorg/DCSA_DOMAIN/1.0.1#/components/schemas/> is a bad namespace for semantic URLs (classes and props) because it violates a number of the CoolUris and "CoolUris for the web" principles. To paraphrase:

• Semantic URLs identify real-world objects and properties, so should be as much free from technology terms as possible. Thus "API", "swaggerhub", "components", "schemas" are parasitic words here.
• "domains" and "DCSA_DOMAIN" are also parasitic.
• Version numbers in URLs are a double-edged sword. On one hand, they allow you to evolve the schema. On the other hand, if you have several billion triples using such namespace and then need to migrate them to new URLs, that's a painful experience. For that reason, very few established ontologies use versioned URLs.
• #/components/schemas/ is a valid JSON Path anchor. However, in semantic URLs, slash is preferred for large collections (of terms or individuals), and hash for small collections. hash-slash is not used.

All said, I'd change that namespace to https://data.dcsa.org/. Ideally, in the future this URL will return classes and properties in various representations: HTML, JSONLD, Turtle, etc

Important takeaway: JSON API and JSON Schema URLs are not necessarily good semantic URLs.

PS: @nissimsan change the title please

[HenrikHL]

Hi @VladimirAlexiev - I suggest you go to SwaggerHub and download the resolved version of the API you are looking for - this would resolve all $refs.
Taking up how SwaggerHub defines their linking here is not the right fora - we use the tools/editor provided by SwaggerHub - we have no control over the hash-slash.

[OR13]

As much as I love OAS, I think it might not be the best choice for defining clean ontologies... I would avoid relying on OAS generated URLs for semantic term definitions, if you have a better option available.

[nissimsan]

@HenrikHL, what we are asking is exposing the terms which are defined by DCSA as nicely resolvable URIs. Such that I can express for example DCSA's definition of a TransportDocument as something like https://dcsa.org/vocab/TransportDocument, resolving to its formal definition.

You have the content, TransportDocument is defined here (bottom of page 32): https://dcsa.org/wp-content/uploads/2020/12/20201208-DCSA-P1-DCSA-Information-Model-v3.0-FINAL.pdf, it's just rather hard to get to.

Inspiration:
https://schema.org/Organization
https://service.unece.org/trade/uncefact/vocabulary/uncefact/#TransportEquipment

[raisoman]

@nissimsan what would the simplest way to achieve that be?

[nissimsan]

There are dedicated tools, jargon.sh is cool, but is probably overkill here. So probably github pages, or however you usually generate web content.

What's important is:

• that URIs are under the DCSA domain. So something like vocab.dcsa.org/Resource or dcsa.org/vocab/Resource
• that uris resolve to human readable description
• that it is static!

[nissimsan]

https://api.swaggerhub.com/domains/dcsaorg/DCSA_DOMAIN/1.0.1#/components/schemas/
... this also has a lot of good terms listed.

Only needs a way to reference them. For example
https://dcsa.org/vocab#800SeriesCarrierCode

The majority of terms used in the DCSA schemas are based on CEFACT, so avoid defining terms which are already defined elsewhere.
https://xkcd.com/927/
:)