Skip to content

XML validation

Various tools have been put together as part of TethysL development. One such tool performs the validation of XML missions according to the Tethys XML Schema. This is mainly used as one final verification after translation from TethysL, which is performed as part of internal unit testing as well as from the editor.

However, since the TethysL Engine API exposes the functionality generically, a simple HTTP request can be used to validate any local XML file.

There are two "routes" (that is, specific API endpoints) for this purpose, in both cases to be exercised with the POST method along with the contents of the file to be validated:

  • https://okeanids.mbari.org/tethysl-engine/validateXml

    This will perform a strict validation, that is, including verification against the Tethys XML Schema.

  • https://okeanids.mbari.org/tethysl-engine/validateXmlBasic

    This will perform just basic XML syntax validation.

You can use any HTTP client tool, e.g., CURL, HTTPie, CURLie. Below are some examples using HTTPie.

By default, the response will be provided in JSON format. If you want a plain text response, use the Accept:text/plain HTTP header as indicated below.

You can validate any XML file available on your system. Only requirements are HTTPie (or other HTTP client tool) and connection to the internet. The examples below assume that your current directory corresponds to a clone of the lrauv-mission repository.

Before we go to the examples, just a couple of notes regarding HTTPie usage:

  • -pb is optional and means "just show the response body"
  • post means we are making a POST request
  • The @ prefix allows to upload the contents of the given file
  • The Accept:text/plain at the end of the command gets captured as a request header

With strict validation

Let's validate Demo/HFRadarModelTest.xml:

Enter: 

http -pb post https://okeanids.mbari.org/tethysl-engine/validateXml @Demo/HFRadarModelTest.xml

Output: 

{
    "error": "cvc-complex-type.2.4.a: Invalid content was found starting with element '{\"Tethys/Derivation\":HFRadarModel}'...
    "line": "109",
    "column": "34"
}

For a plain text response, add Accept:text/plain at the end of the command:

Enter: 

http -pb post https://okeanids.mbari.org/tethysl-engine/validateXml @Demo/HFRadarModelTest.xml Accept:text/plain

Output: 

Error in line 109, column 34:
cvc-complex-type.2.4.a: Invalid content was found starting with element '{"Tethys/Derivation":HFRadarModel}'...

With basic validation

http -pb post https://okeanids.mbari.org/tethysl-engine/validateXmlBasic @Demo/HFRadarModelTest.xml Accept:text/plain

ok

Note

Due to the underlying library used in the backend, only the first error will be reported for a file.

Pre-commit hook

A basic pre-commit git hook has also been written, intended to help XML mission authors perform the validation to any new or modified files as part of the commit command.

This hook is a bash script that uses the mechanism above, and is available for download from here:

xmlValidation-pre-commit.sh.

Make a copy as .git/hooks/pre-commit in your local lrauv-mission repository. If you already have some pre-commit logic in that file, you could add an invocacion to xmlValidation-pre-commit.sh. (Note that this is a client-side hook.)

By default, the validation will be strict. To adjust the desired validation level, run:

git config hooks.xmlValidation <level>

where <level> is one of strict, basic, or none.

When you commit your changes, e.g.: 

git commit -am 'testing pre-commit hook'

the output of the hook will look something like the following in case there are any validation errors involving the affected files:

- Validating M Engineering/LBLTest.xml ...
- Validating M Transport/keepstation_3km.xml ...

Error: Attempting to commit invalid XML file(s) using xmlValidation=strict

- M Engineering/LBLTest.xml:
Error in line 43, column 25:
cvc-complex-type.2.4.a: Invalid content was found starting with element '{"Tethys/Navigation":LBL}'. One of '{"Tethys":Aggregate, "Tethys":Behavior, "Tethys":Call, "Tethys":Insert, "Tethys":ReadData, "Tethys":ReadDatum, "Tethys":SendData, "Tethys":SendStr, "Tethys":Syslog, "Tethys":Assign}' is expected.

- M Transport/keepstation_3km.xml:
Error in line 10, column 17:
Attribute name "Vehicle" associated with an element type "Description" must be followed by the ' = ' character.

(M and A are shorthands for "modified" and "added" as reported from the underlying git diff command used by the hook.)