subcheck’s core interfaces are based on RESTXQ and are implemented in the BaseX XML Server as a pure XQuery application.

The service contains a single endpoint /validate that orchestrates the validation engine and returns the resulting report. Files that are uploaded by users will not be persisted by the engine, they are parsed and validated in memory only and returned to the caller right away. The report will be returned in its XML form by default, but other formats are possible.

The XQuery implementation receives an XML file — it returns an error on non-XML files — and runs the XSL transformation for the compiled rules. The result of this process is then passed on to another stylesheet that transforms it to the reporting format and if necessary conducts conversions to other formats such as JSON or text.

In practice, a request looks like the following:

$ cat luggage.xml | http POST http://subecheck/validate
###################################################
> Content-Type: application/xml; charset=UTF-8

  <report>
    <errors>
    <constraintID>c1</constraintID>
    <title>
     Cabin Bag Max. Weight 8kg
    </title>
    <shortUserDesc>
      Cabin bag should not have more than 8kg weight.
    </shortUserDesc>
    ...
  </report>

Via REST, users can also request a report in JSON format by specifying a different Accept-Header:

$ cat luggage.xml | http POST http://subecheck/validate Accept:application/json
###########################################################################
> Content-Type: application/json; charset=UTF-8

{
  "filename": "luggage.xml",
  "filesize": "2 KB",
  "report": [{
    "constraintID" : "c1",
    "title"        : "Cabin Bag Max. Weight 8kg",
    "shortUserDesc": "Cabin bag should not have more than 8kg weight.",
    "longUserDesc" : "Assertion: The weight of cabin […]",
    "specs"        : [{
      "errorLevel" : "ERROR",
      "name"       : "Conditons Aeto, Version 1.0",
      "nameAcronym": "C-Aeto",
      "section"    : "[…]",
      "text"       : "[…]",
      "uri"        : "https://c-aeto/spec"
    }],

While subcheck was designed with arbitrary frontends in mind — i.e. it can be easily integrated into existing workflows thanks to its almost universally accessible REST interface — we decided to implement a visual interface as a proof-of-concept that allows users to interactively explore and assess their validation results.

This interface heavily builds on the JSON-serialization of the reports and is implemented as a Single-Page-Application made up of Vue.js-components, that allow the user to potentially browse and filter hundreds of validation messages.