enketo-validate

Enketo Validate

Validate ODK XForms using Enketo's form engine

This app can be used:

1. via the command-line, e.g. in a non-javascript form builder such as pyxform.
2. as a nodeJS module to be used in your own javascript application

Live demo web application (meant for testing purposes only) that uses Enketo Validate (and ODK Validate) as a module: validate.enketo.org (source code)

Technical Documentation

Prerequisites

1. install nodeJS 12
2. install build tools for native modules with apt-get install build-essential

Via Command-line

Command-line Install

To make the enketo-validate command available from any folder on your machine.

$ npm install -g --production enketo-validate`

Alternatively, you can clone the repo and run npm install --production. This will make the ./validate command available from within the clone folder. Running npm link makes the enketo-validate command available from any folder on your machine.

Command-line Use

$ enketo-validate path/to/form.xml

Errors are returned to stderr and warnings to stdout. If there is no stderr output the form is valid.

Command-line Help

$ enketo-validate --help

Command-line update

1. npm install -g --production enketo-validate

As NodeJS module

Module installation

npm install enketo-validate --save

Module Use

const validator = require('enketo-validate');

// Options:
// debug: [boolean] outputs unadulterated errors instead of cleaned ones
// openclinica: [boolean] runs the validator in a special OpenClinica mode
const options = {};

// Read the xform as string
const result = validator.validate( xformStr, options );

// The result has the following format:
// {
//      warnings: [ 'a warning', 'another warning'],
//      errors: ['an error', 'another error'],
//      version: "0.0.0"
// }
// if errors.length is 0, the form passed validation

How it works

In it's current iteration, the validator does the following:

• It checks whether the XForm is a valid XML document.
• It performs some elementary ODK XForm structure checks.
• It checks if each bind nodeset exists in the primary instance.
• It checks if appearance values are supported or deprecated for that type of question.
• It checks for each <bind> whether the relevant, constraint, calculate, and required expressions are supported and valid* XPath.
• It checks whether required <label> elements exist.
• It checks for duplicate question or group names.
• It checks for nested repeats.
• It checks for form controls that have a calculation but are not set as readonly.

* Note, that /path/to/a/nonexisting/node is perfectly valid XPath.

Funding

The development of this application was funded by OpenClinica.

License

See the license document for this application's license.

Change log

See change log