Skip to content
An ODK XForm validator around the Enketo form engine.
JavaScript Other
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
build
docs
src
test
.editorconfig
.eslintrc.json
.gitignore
.jsbeautifyrc
.travis.yml
CHANGELOG.md
LICENSE
README.md
appveyor.yml
build-binary.sh
jsdoc.config.js
nyc.config.js
package-lock.json
package.json
rollup.config.js
rollup.utils.config.js
update-readme-with-shield-badge.js
validate
windows-build-binary.bat
windows-build-binary.sh

README.md

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

You can’t perform that action at this time.