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

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

> On Thu, Mar 14, 2024 at 7:06 AM Thomas Francart
> <thomas.francart@sparna.fr> wrote:
> > Basically, the social aspect of exchanging and documenting context is
> simply not addressed, and this is frustrating. JSON-LD contexts are not
> only for machines. Sometimes technical people look at them to use and
> understand them, we need to carry some documentation information for this.
> > How can this be addressed ?
>
> We had discussed a "@comment" keyword in the past, though there were
> good reasons a number of people argued against it (it's non-standard,
> bloats the markup during runtime, etc.). Some argued that the best
> thing to do might be to just use the syntaxes commenting mechanism,
> such as YAML-LD using "#". Others noted that using "rdfs:comment"
> would be better. Still others noted that the place for commentary is
> in the human-readable vocabulary documentation, and if commentary is
> needed, it should go in the specification and not the JSON-LD Context.
>
> At present, I believe we just don't have consensus on a SINGLE
> approach forward given that there are benefits and drawbacks to each
> approach above. No one has been able to convince the community that we
> need a single mechanism for commenting in JSON-LD Contexts.
>

Thanks. We don't have a SINGLE approach, but do we have an approach **at
all** ?

   - @comment does not exist
   - there is no JSON syntax commenting mechanism (which was a stupid
   decision, if you ask me), and I will not switch to YAML-LD (or maybe I will
   in the future, just for this reason)
   - the use of rdfs:comment (or other annotation) is not possible, as my
   previous example showed
   - this does not belong to the vocabulary documentation, since we are
   here at the syntactic level, not the semantic level (although of course, we
   are mapping the two)

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.

Thomas


> -- 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