search

TimLuq / schematron-runner

2 stars 3 forks source link

readme

schematron-runner

Build Status npm version license dependencies Status Coverage Status

A javascript implementation of schematron testing for XML documents. This specifically resolves a need for a package that allows a quick, reliable install for validating HL7 clinical documents, such as C-CDA.

Due to schematron-runner being written in TypeScript. This grants typing and typechecking possibilities if this project is used as a libary.

Table of Contents

Install

For the CLI application to be available system wide you may wish to install globally. If you wish to use it for a project a module installation is recommended.

Using npm:

npm install schematron-runner # project
npm install -g schematron-runner # global

Using yarn:

yarn add schematron-runner # global
yarn global add schematron-runner #project

Building from source:

git clone git+https://github.com/TimLuq/schematron-runner.git
cd schematron-runner
npm install

Prebuilt files

The published packages includes a number of files in the build directory. I recommend you to use a bundler, such as rollup or webpack, if your project is an end product. But these files are provided for other uses.

CLI

After installation (or by running npx) an executable program named schematron-runner is available.

For information about CLI usage run schematron-runner --help.

API

The following APIs are available.

Example: Validating xml

import { validate, validateFocused, webDefaults } from "schematron-runner";
import { promises as fs } from "fs";

const xmlPath = 'someFile.xml';
const schematronPath = 'someFile.sch';

(async () => {
    const xml = await fs.readFile(xmlPath, "utf8");
    const schematron = await fs.readFile(schematronPath, "utf8");

    const results = await validate(xml, schematron);
    // do stuff with results
})();

File paths can also be passed to the validator directly. The following lines all return the same results:

const results0 = await validate(xml, schematronPath);
const results1 = await validate(xmlPath, schematron);
const results2 = await validate(xmlPath, schematronPath);

Interface: Options

The validate and validateFocused functions takes an options object as an optional argument. These options may be used to change the behavior of the validation.

Below is an example with warnings disabled and using web compatible defaults:

const results = await validateFocused(xml, schematron, webDefaults(), {
    excludeWarnings: true
});

Interface: Results

The results object contains arrays errors, warnings, passed and ignored.

The errors, passed, and warnings arrays are reported as determined by the schematron and test descriptions. They are instances of the following form:

{
    type: type,                     // "error" or "warning"
    test: test,                     // xpath test
    simplifiedTest: simplifiedTest, // xpath test with resource values included, if applicable, null otherwise
    description: description,       // schematron description of the test case
    line: line,                     // line number of the violating context
    path: path,                     // xpath path of the violating context
    patternId: patternId,           // schematron-assigned pattern id
    ruleId: ruleId,                 // schematron-assigned rule id
    assertionId: assertionId,       // schematron-assigned assertion id
    context: context,               // xpath context of the rule
    xml: xml                        // xml snippet of the violating context
}

The ignored tests are those that resulted in an exception while running (eg. the test is invalid xpath and could not be parsed properly) and require manual inspection. They are of the following form:

{
    errorMessage: errorMessage,     // reason for the exception/ignoring the test
    type: type,                     // "error" or "warning"
    test: test,                     // xpath test
    simplifiedTest: simplifiedTest, // xpath test with resource values included, if applicable, null otherwise
    description: description,       // schematron description of the test case
    patternId: patternId,           // schematron-assigned pattern id
    ruleId: ruleId,                 // schematron-assigned rule id
    assertionId: assertionId,       // schematron-assigned assertion id
    context: context,               // xpath context of the rule
}

clearCache ()

The validator uses a cache to store parsed schematrons, an intermediate data structure used to store revelant schematron information. This reduces the runtime of the validator when validating against the same schematron multiple times.

validate (xml, schematron[, options])

Equivalent of calling validateFocused(xml, schematron, polymorphicDefaults(), options). See Interface: Results for description of the results object.

validateFocused (xml, schematron, defaults[, options])

Validates a document against a schematron ruleset. See Interface: Results for description of the results object.

parseSchematron (document)

Parse a schematron document to an internal representation. Might be usefull for displaying the discovered parts of a schematron file.

polymorphicDefaults (field, type)

The provider will prefer gobal objects as if in a web context. If the global objects are not set it will load external packages to provide the functionality.

For the prebuilt build/schematron-browser.js this is an alias for webDefaults.

throwDefaults (field, type)

The provider will throw when called. A full options object must have been used.

webDefaults (field, type)

The provider will use gobal objects as if in a web context. If the global objects are not set it will throw or result in an undefined state.

License (MIT)

Copyright © 2017 Eric Wadkins, 2018-2019 Tim Lundqvist.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.