Skip to content

enketo/enketo-validate

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

66 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

coverage-shield-badge-1 npm version Build Status Dependency Status devDependency Status

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 8+
  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/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