ShEx/API

From Semantic Web Standards
Jump to: navigation, search

Obsolete - please see the ShEx github wiki


ShEx API

Design questions

  • describe with WebIDL?
  • is it prescriptive or descriptive (or how specific should it be)?
  • what language bindings exist for non-Javascript?
  • should it use Promises?

related Git issues

related docs

Use Scenarios

  • library interoperability -- be able to swap implementations, e.g. from ShExScala over Jena to Iovka's implementation over BlazeGraph
  • REST service description -- describe service invocation (i.e. starting a server on the command line) and execution (GET conformance results)
  • truth maintenance -- update ShapeMap resource with dispositions of individual node/shape pairs.
  • Validation of updates -- Limit the validation only to nodes that are added or modified

ShapeMap

See proposed ShapeMap specification.

The different uses cases call for a similar ShapeMap structure with additional features depending on the rule in validation, e.g. a question (list of node/shape pairs to investigate), a premise (list of node/shape pairs and their associated results which will be assumed accurate) or a result (list of node/shape pairs and the results that the validator is returning).

Structure

   { node: n,
     shape: s,
     conforms: true|false, OR status: pending|conformant|nonconformant,
     reason: string, OR reason: arbitrary structure,
     myextra1: ..., myextra2: ... OR appInfo: { myextra1: ..., myextra2 ... }
   }

Surface Syntax

example:

   d:n1@s:S1,
   "foo"%5E%5Exs:string@s:S2!/"missing p1"$appinfo:{"myextra1":"...", "myextra1":"..."},
   "chat"%40en-fr@<http://...S3>?

where ! means nonconformant, ? means pending, / introduces a reason and '$' introduces a JSON identifier with an arbitrary JSON value.

Punctuation choices: '~' | '.' | '!' | '$' | '&' | "'" | '(' | ')' | '*' | '+' | ',' | ';' | '=' | '/' | '?' | '#' | '@' | '%'
noting that '&', ',', ';' and '=' are used for CGI separators, '%' is a CGI character escape and '#' is a fragment ID.

A minimally-encoded version of the example would require escaping on '@', ',', '$', '!', '?', '.', e.g.:

   d:n1@s:S1,
   "foo"%5E%5Exsd:string@s:S2!/"missing p1"$appinfo:{"myextra1":"..."%2C"myextra1":"..."},
   chat"%40en-fr@<http://...S3>?

Use Cases

  • node/shape pair
    validate(schema, data, node, shape) => result
    • result is T/F
    • result is ShapeMap
      • return orig ShapeMap with status
      • return orig ShapeMap with status plus related nodes
        • related nodes = all NodeConstraints and Shapes
          n1@s1,n1@s2!
        • related nodes = labeled NodeConstraints and Shapes
        • related nodes = labeled Shapes
        • related nodes = coreferenced Shapes
  • set of node/shape pair
    validate(schema, data, question) => results
  • long-running process
  • ShapeMap as premise
    validate(schema, data, premise, question) => results
    where premise, coverage and results are all subsets of the full structure.