dual documentation

[VladimirAlexiev]

As discussed on 29 Mar, we need to produce two closely related but not identical documentations:

• JSON and JSONLD fields, as shown at the web app https://ns.mh1.eu/epcis/
  • Can this also serve as XML documentation? XSD allows embedded docs, but the EPICS 1.2 XSD, afair, include no docs
  • I don't know a way to attach documentation to JSON Schema
• Ontology documentation (classes and properties)
  • It's clear how to attach it inside the ontology
  • It could be served with the same app, and/or a standard ontology doc generator like LODE, Widoco, pyLODE etc

What should be the input?

• Obviously we should use a single-source approach as much as possible, with the differences delineated in a machine-readable way
• Must be simple enough so GS1 domain experts without RDF experience can edit definitions
  • IMHO it's best to use some google sheets and generate from those
• Should be usable by the web app and ontology generators

I could devise some simple RDF way to capture this (using namespace gs1_meta:), eg

epcis:EPCISEvent a rdfs:Class;
  gs1_meta:definiton "A logistics event ...";
  gs1_meta:uriProperty epcis:eventID;
  rdfs:comment  # concatenated from own definition and uriProp's definition
"""A logistics event ... 
Its URI (called `eventID` in JSON-LD) is (Optional)... ni:///...
""".

epcis:eventID a gs1_meta:Property;
  gs1_meta:definiton "(Optional)... ni:///...".

@mgh128 would this work for you?

[mgh128]

JSON Schema is written in JSON. JSON doesn't support comments. Therefore JSON Schema can't support comments.

I am happy for us to add further comments, annotations and cross-references within the Linked Data ontology we're developing for EPCIS and CBV.

I don't expect it to serve as the entire documentation for the XML data binding. It already has its XSD with comments. It's also very clunky.

We did very briefly consider JXON (see https://www.balisage.net/Proceedings/vol7/html/Lee01/BalisageVol7-Lee01.html and elsewhere) but have not devoted much effort to this.

I agree that we should consider a non-RDF mechanism (e.g. Google Sheets) way of enabling anyone in the work group to improve on definitions, then use this as the master document and run a script to generate the RDF / JSON-LD from that. We can take the initial draft of the Linked Data ontology and run a SPARQL query to convert it into spreadsheet format that can be edited more easily by others (mainly focusing on the definitions etc.)

[nathanclevenger]

Have you considered using YAML as the place to store the comments? You can have both YAML and JSON versions of the JSON schema, but YAML does support comments.

On Tue, Apr 6, 2021 at 5:40 AM Mark Harrison @.***> wrote:

JSON Schema is written in JSON. JSON doesn't support comments. Therefore JSON Schema can't support comments.

I am happy for us to add further comments, annotations and cross-references within the Linked Data ontology we're developing for EPCIS and CBV.

I don't expect it to serve as the entire documentation for the XML data binding. It already has its XSD with comments. It's also very clunky.

We did very briefly consider JXON (see https://www.balisage.net/Proceedings/vol7/html/Lee01/BalisageVol7-Lee01.html and elsewhere) but have not devoted much effort to this.

I agree that we should consider a non-RDF mechanism (e.g. Google Sheets) way of enabling anyone in the work group to improve on definitions, then use this as the master document and run a script to generate the RDF / JSON-LD from that. We can take the initial draft of the Linked Data ontology and run a SPARQL query to convert it into spreadsheet format that can be edited more easily by others (mainly focusing on the definitions etc.)

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/gs1/EPCIS/issues/238#issuecomment-814016211, or unsubscribe https://github.com/notifications/unsubscribe-auth/AA7QQXULLJM2O5VVEUTVH43THLQJZANCNFSM42FD5O6Q .

[mgh128]

@nathanclevenger Thanks for the suggestion. YAML supports comments but they're lost as soon as you convert YAML to JSON. Plenty of programming / scripting languages have built-in support for JSON (e.g. JSON.parse(), JSON.stringify() in JavaScript) but don't have built-in support for parsing / outputting YAML.

[VladimirAlexiev]

• Mark: ideally, we should be able to produce JSON and RDF documentation from the same source
• Vladimir: they should be hosted at slightly different URLs: the RDF at the ontology URL, and the JSON documentation at another URL.
• We'll consider merging the ontology and SHACL in one file, because it makes sense to declare each class to also be a SHACL Shape (and use the shape-class binding shortcut): we don't have classes used in a "polymorphic" way
• Then the best way to describe the "URI pseudo-properties" (eg eventID is with a NodeShape): then Mark can use the info in that NodeShape (incl label) to display it as a JSON property.

[VladimirAlexiev]

@mgh128 my latest commit removes eventID, id from ontology in turtle. It also replaces all anyURI props with ObjectProperties.

And we still haven't worked out a way to make good jsonld from it.

Once we decide the appropriate way to express the pseudo props, I'll add them back.

[VladimirAlexiev]

Jose prefers to use something standard, rather than our own "pseudo property" or "meta property". Which indicates a SHACL "node constraint"

[VladimirAlexiev]

@mgh128 Currently I'll submit a PR with 2 meta-props:

epcis:jsonldLabel a owl:DatatypeProperty , rdf:Property ;
      rdfs:comment      """JSONLD term (alias) used for this property.
The default is the property local name, which is captured in rdfs:label."""@en ;
      rdfs:domain       rdf:Property;
      schema:domainIncludes rdf:Property ;
      rdfs:isDefinedBy  epcis: ;
      rdfs:label        "jsonldLabel" ;
      rdfs:range        xsd:string ;
      schema:rangeIncludes xsd:string ;
      sw:term_status    "stable" .

epcis:jsonldUriLabel a owl:DatatypeProperty , rdf:Property ;
      rdfs:comment      """JSONLD term (alias) used for the URI of nodes of this class.
There is no default: many EPCIS classes use blank nodes instead of the standard @id JSONLD term."""@en ;
      rdfs:domain       rdf:Property;
      schema:domainIncludes rdf:Property ;
      rdfs:isDefinedBy  epcis: ;
      rdfs:label        "jsonldLabel" ;
      rdfs:range        xsd:string ;
      schema:rangeIncludes xsd:string ;
      sw:term_status    "stable" .

Used like this:

epcis:AggregationEvent   a owl:Class , rdfs:Class ;
        epcis:jsonldUriLabel "eventID".
epcis:measurementType a owl:ObjectProperty , rdf:Property ;
        epcis:jsonldLabel "type".
epcis:sourceOrDestination  a owl:ObjectProperty , rdf:Property ;
        epcis:jsonldLabel "source", "destination".

@jmcanterafonseca-iota Can you provide an example of how to do this with SHACL?

[VladimirAlexiev]

@CraigRe, @RalphTro I edited "EPCIS Semantics" and split off subsec 11.4.1 Meta-Properties, and updated the text to reflect the above. If you've published this document, please update it.

[VladimirAlexiev]

@mgh128 @mkotoff

We need to decide what to use for ttl->jsonld.

• riot -formatted jsonld EPCIS.ttl > EPCIS.jsonld infers a richer context then can use simpler data, eg

  "domainIncludes" : {
    "@id" : "http://schema.org/domainIncludes",
    "@type" : "@id"
  },
  {
  "@id" : "epcis:action",
  "domainIncludes" : [ "epcis:AssociationEvent", "epcis:ObjectEvent", "epcis:AggregationEvent", "epcis:TransactionEvent" ],
  }

• Martin used some other tool that uses this nice way of expressing lists (whereas riot uses blank nodes):

  "owl:unionOf":{
        "@list":[
          {
            "@id":"gs1:Product"
          },
          {
            "@id":"gs1:ProductBatch"
          }
        ]
      }

  Note to self: riot is EPCIS.jsonld (61k), Marto's tool is EPCIS-old.jsonld (78k, and older version with less info)

[VladimirAlexiev]

@mgh128 as mentioned in https://github.com/gs1/EPCIS/issues/172#issuecomment-964914441 there are 3 mistakes in jsonldUriLabel, should be as below. Can you fix them in EPCIS.ttl?

epcis:jsonldUriLabel a owl:DatatypeProperty , rdf:Property ;
      rdfs:domain       rdfs:Class;
      schema:domainIncludes rdfs:Class ;
      rdfs:label        "jsonldUriLabel" ;