ShEx/API
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?
- URI for validator schema [IDL]
- Mime type for validator schema [IDL]
- ShExJ Content Type [question]
- @context and shexc for ShapeResults [IDL]
- url-able ShExErrorCode [IDL]
- reusable validator [IDL]
- Design a nice logo for ShEx
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
- related nodes = all NodeConstraints and 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.