yuhaoban / validate

ODK Validate is a Java application for confirming that a form is valid and compliant with the ODK XForms specification. Contribute and make the world a better place! ✨🔍✨

ODK Validate

ODK Validate is a desktop Java application for confirming that a form is compliant with the ODK XForms spec.

ODK Validate is part of Open Data Kit (ODK), a free and open-source set of tools which help organizations author, field, and manage mobile data collection solutions. Learn more about the Open Data Kit project and its history here and read about example ODK deployments here.

• ODK website: https://opendatakit.org
• ODK Validate usage instructions: https://opendatakit.org/use/validate
• ODK forum: https://forum.opendatakit.org
• ODK developer Slack chat: http://slack.opendatakit.org
• ODK developer Slack archive: http://opendatakit.slackarchive.io
• ODK developer wiki: https://github.com/opendatakit/opendatakit/wiki

Setting up your development environment

1. Fork the validate project (why and how to fork)

2. Clone your fork of the project locally. At the command line:

    git clone https://github.com/YOUR-GITHUB-USERNAME/validate
   

We recommend using IntelliJ IDEA for development. On the welcome screen, click Import Project, navigate to your validate folder, and select the build.gradle file. Use the defaults through the wizard. Once the project is imported, IntelliJ may ask you to update your remote maven repositories. Follow the instructions to do so.

The main class is org.opendatakit.validate.FormValidator.

Running the project

To run the project, go to the View menu, then Tool Windows > Gradle. run will be in odk-validate > Tasks > application > run. Double-click run to run the application. This Gradle task will now be the default action in your Run menu.

You must use the Gradle task to run the application because there is a generated class (BuildConfig) that IntelliJ may not properly import and recognize.

To package a runnable jar, use the jar Gradle task.

How Validate validates

Validate is a thin wrapper around the JavaRosa form parsing library. Validate uses JavaRosa to parse an ODK XForms form definition into an in-memory representation. Validate then goes through the in-memory representation in the same way a client such as Collect would. This simulates displaying questions to the user and exercises the logic in the form. Errors detected by JavaRosa are presented to the user.

Validate does not simulate entering any data. Expressions that are not reached when first displaying a form are not verified. For example, if an if call has an invalid function call in one of its branches such as if (/data/my_var = 'yes', invalid-function('bad', 'bad'), 0), Validate will not identify that unless the default value for my_var is yes.

In general, issues with validation or what errors get presented are JavaRosa issues and should be filed in its repository.

Integrating Validate with your Java app

1. Download the latest ODKValidate jar or build your own.

2. Add the ODKValidate jar to your classpath.

3. Create a custom ErrorListener by implementing the org.opendatakit.validate.ErrorListener interface.

4. Add the custom ErrorListener to the form validator and call any of the various validate(...) methods.

See example below:

ErrorListener listener = new ErrorListener() {
    public void error(Object err) {
        // ...custom code to handle error message
        System.err.println(err);
    }

    public void error(Object err, Throwable t) {
         // ...custom code to handle error message and exception
        System.err.println("" + err + t);
    }

    public void info(Object msg) {
        // ...custom code
        System.out.println(msg);
    }
};

new FormValidator().setErrorListener(listener).validateText("<xform>...");

Calling Validate via the command line interface

You can use Validate through the command line like this: java -jar ODKValidate.jar [--fail-fast] path/to/xform.xml [FORM...].

An exit code of 0 means Valid XForm and 1 is Invalid XForm.

Contributing code

Any and all contributions to the project are welcome. ODK Validate is used across the world primarily by organizations with a social purpose so you can have real impact!

If you're ready to contribute code, see the contribution guide.

Downloading builds

Per-commit debug builds can be found on CircleCI. Login with your GitHub account, click the build you'd like, then find the JAR in the Artifacts tab under $CIRCLE_ARTIFACTS/libs.

Current and previous production builds can be found on the ODK website.