Re: How do you document your JSON-LD context files ?

Hello

Le jeu. 14 mars 2024 à 15:18, Manu Sporny <msporny@digitalbazaar.com> a
écrit :

> On Thu, Mar 14, 2024 at 9:40 AM Thomas Francart
> <thomas.francart@sparna.fr> wrote:
> > Thanks. We don't have a SINGLE approach, but do we have an approach **at
> all** ?
>
> Yes, we do -- put any explanation of design decisions in the
> vocabulary or in a specification. The place to explain design
> decisions is DEFINITELY NOT in a JSON-LD Context. We have pretty solid
> consensus on that at this point, IMHO.
>

Sorry, I wrote "design decisions", but that was not the proper wording. I
know the design decision of the vocabulary better fit, well, in the
vocabulary.
What I really want to document is the *JSON-LD context itself* :

   - mapping declarations may be grouped in sections e.g. typically, an
   id+type mapping at the top, then a section on namespace mapping, then a
   section on class identifier mappings, then a section on property mappings,
   or maybe the property mappings grouped in per-class section. How can I make
   this organisation in sections explicit ?
   - I need to write syntactic mappings that are *not* part of the
   vocabulary : typically a @reverse mapping, that is here because of purely
   syntactic reasons, and that is not part of the vocabulary (see my previous
   example about a @reverse mapping of a schema.org property). How can I
   make that explicit ? it does not belong to the RDFS vocabulary.
   - I may need to document JSON-LD framing specifications as well


> > How am I supposed to convey to say, a team of developper, the decisions
> taken while designing the context ? and a framing spec ?
> > I am not blaming anyone but this is a very frustrating situation.
>
> I'm sorry to hear that you're frustrated. :(
>
> The good news is that there is a pretty clean answer to your question:
>
> Document the design decisions in a specification or vocabulary, and
> (ideally), make the URLs used in the JSON-LD Context link back to
> human-readable documentation. Here's how we do it for Verifiable
> Credentials:
>
> https://w3c.github.io/vc-data-model/vocab/credentials/v2/vocabulary.html
>
> That is generated through Ivan Herman's wonderful yaml2vocab tool:
>
> https://github.com/w3c/yml2vocab
>
> Would that work for your situation, Thomas?
>

Thank you very much, the structure of the @context file with nested
@context is very smart and definitely a source of inspiration. However it
does not quite work for me in terms of documentation.
I know how to specify and document a vocabulary (I even have my own
SHACL-based tool for that). In my situation, the application profile is
already documented (if you are curious [1] and [2])
Now I would like to specify and document the semantic-syntactic mapping
from that application profile to one particular JSON structure (there may
be other such JSON structures for the same AP).
As it does not belong to the semantic layer, and as I can't do it in the
intermediate mapping layer, I will probably rely on the syntactic layer :
JSON schema does have a $comment key (
https://json-schema.org/understanding-json-schema/reference/comments)

Cheers
Thomas

[1] :
https://www.issn.org/understanding-the-issn/assignment-rules/issn-linked-data-application-profile/
[2] :
https://www.issn.org/wp-content/uploads/2020/09/ISSN-LinkedDataApplicationProfile-v2_0.pdf


>
> -- manu
>
> --
> Manu Sporny - https://www.linkedin.com/in/manusporny/
> Founder/CEO - Digital Bazaar, Inc.
> https://www.digitalbazaar.com/
>


-- 

*Thomas Francart* -* SPARNA*
Web de *données* | Architecture de l'*information* | Accès aux
*connaissances*
blog : blog.sparna.fr, site : sparna.fr, linkedin :
fr.linkedin.com/in/thomasfrancart
tel :  +33 (0)6.71.11.25.97, skype : francartthomas