API

Migrated from https://www.w3.org/2001/sw/wiki/ShEx/API

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

• 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

related docs

• draft specification
• sketch of stateless API implemented over stateful API
• ShExMap

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
• executeion of EXTERNAL shape expresssions, e.g. for large or computed datasets

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@&lt;<nowiki>http://...S3</nowiki>&gt;?

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@<nowiki><http://...S3></nowiki>?

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.