search

getodk / 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! ✨🔍✨
https://docs.getodk.org/validate/
Other
9 stars 27 forks source link

Add description of what validation is performed #78

Closed lognaturel closed 5 years ago

lognaturel commented 5 years ago

Provides a bit more context on what Validate actually does. In particular, the fact that the form is actually walked through is not obvious.

yanokwa commented 5 years ago

I think the text could be shorter and punchier. Also makes sense to me to go after "Running the project".

How Validate validates

Validate is a thin wrapper of 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.

lognaturel commented 5 years ago

The reason I didn't want to put it after "Running the project" is that I think people stop reading once they have a dev env set up. This increases the odds of someone actually reading the text, I think.

yanokwa commented 5 years ago

Disagree with that rationale. It really feels like it groups better with the stuff after setup. I do think it also needs to be in the user facing Validate docs and featured front and center there.

lognaturel commented 5 years ago

🤷🏻‍♀️