Figure out best pattern for linking from bits of ShEx (smaller than shapes) to documentation URLs

[danbri]

For a concrete example, consider https://github.com/google/schemarama/blob/main/demo/validation/shex/specific/ServiceB/Dataset.shex

which was in fact based on Google's rules for describing datasets to Google Dataset Search. This all got anonymized for the opensource launch here for simplicity.

Here's a fragment of the ShExC:

<#ValidServiceBDataset> @<#ValidSchemaDataset> AND EXTRA a {
    schema:description .
    // techdoc:url "https://schema.org/url"
    // techdoc:description "A short summary describing a dataset."
    // techdoc:identifier "error";

    schema:name .
    // techdoc:url "https://schema.org/name"
    // techdoc:description "A descriptive name of a dataset."
    // techdoc:identifier "error";

    schema:alternateName . +
    // techdoc:url "https://schema.org/alternateName"
    // techdoc:description "Alternative names that have been used to refer to this dataset, such as aliases or abbreviations."
    // techdoc:identifier "warning";

    schema:creator . +
    // techdoc:url "https://schema.org/creator"
    // techdoc:description "The creator or author of this dataset."
    // techdoc:identifier "warning";

    schema:citation .
    // techdoc:url "https://schema.org/citation"
    // techdoc:description "Identifies academic articles that are recommended by the data provider be cited in addition to the dataset itself."
    // techdoc:identifier "warning";
...

• First thing to note: the techdoc: prefix is bound to schema.org's URI. We just called it something different to avoid mixing up the layers.
• Second: the example URLs here are boring links to schema.org. The intent is that they should be deep links into the relevant service documentation. For example, for isBasedOn in this set of shapes we might point to this section of the docs.
• Third: the // construction is an explicit annotation mechanism in ShExC, not just a comment.

It might be that the linking from bits of ShEx to supporting documents is better supported by out-of-band metadata, rather than inline. To be discussed!

[danbri]

@ericprud has mentioned "shape paths" in this context.

out-of-band is important...