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.