Edit online

Validate

Attention: This script is bundled with the all platforms distribution of Oxygen XML Editor. To run the script, you are required to purchase a special scripting commercial license.

All the validations possible in Oxygen XML Editor can also be performed from scripting. This includes validating various types of XML schemas, such as XSD, RNG, RNC, DTD, and NVDL, as well as JSON Schema, XProc, ANT, XSLT, XQuery, CSS, LESS, HTML, WSDL, OpenAPI, and of course, XML with XML schema, and JSON/YAML with JSON Schema.

The Validate script (validate.sh, found in the scripts subfolder inside Oxygen's installation directory) can be used to validate a file or a directory and get the validation results in various formats.

Arguments for the Transform Script

sh scripts/validate.sh fileOrDirPath [-s schemaFilePath | -sn scenarioName] [-sf scenariosFilePath] [-if includeFilesFilter] [-ef excludeFilesFilter] [-ed excludeSubdirsFilter] [-rf reportFile] [-rft reportFormat] [-v] [-help | --help | -h | --h]
fileOrDirPath
Mandatory argument that specifies the path of the file or directory to validate (it can also be provided as a URL, but if you are validating directories, the only protocol considered is 'file://').
-s schemaFilePath
Optional argument that specifies the file path of the schema to validate against (it can also be provided as a URL).
-sn scenarioName
Optional argument that specifies the name of the validation scenario to be applied.
-sf scenariosFilePath
Optional argument that specifies the path of the file that stores the validation scenarios (either an Oxygen scenarios file or an Oxygen project file). It can also be provided as a URL.
Notes:
  • The file that stores the validation scenarios must have a similar format to that generated from Oxygen by invoking Export Global Validation Scenarios from the Options menu. This type of Oxygen-generated scenarios files has a .scenarios file extension by default and contains all the necessary information about custom validation scenarios created in Oxygen.
  • Oxygen also saves the custom validation scenarios (as well as the scenario associations made explicitly for the files you work with) in special formatted Oxygen project files (usually with the .xpr file extension). Therefore, by using the arguments provided through -sn and -sf options, you can apply any scenario that was previously stored in either a scenarios file or an Oxygen project file.
  • The -s and -sn options are mutually exclusive. Specifying both in the same command line is not allowed.
-if includeFilesFilter
Use this argument to only validate the files that match the specified pattern (e.g. .xml,.json). The default value is *.
-ef excludeFilesFilter
Excludes the files that match the specified pattern (e.g. test.wsdl,draft.xsl) from the validation.
-ed excludeSubdirsFilter
Excludes the sub-directories that match the specified pattern (e.g. .svn,_svn,.git).
-rf reportFile
Specifies the path for the report file to save the validation results, instead of presenting them in the console. The content of the report file is formatted according to the -rft argument. The report file path can also be provided as a URL.
-rft reportFormat
Specifies the format of the validation report. Possible values: txt, text, xml, json, html, htm. Default values: txt, text.
-v
Prints additional information to the console (Verbose mode).
-help | --help | -h | --h
Displays help text.
Additional Notes:
  • Avoid activating the Verbose mode (-v option) when opting to redirect the console (and the validation report implicitly) to a specific file. That is done using the > operator instead of the -rf option. The additional information provided through verbose mode is also saved to the report file, making it to be reported as invalid when inspected in specialized editors. However, that information is placed at the beginning of the report, as plain text. If removed, the report should become valid.
  • If the validation uses the Saxon engine and you do not have a commercial license, then the script automatically uses the Saxon Home Edtion distribution that does not require a license. However, if the validation involves specific Saxon Personal / Enterprise Edition advanced features, then the validation report clearly signals that an appropriate Saxon license was not found. Placing a valid Saxon license file in the lib directory from the Oxygen installation folder solves the problem and the validation operation works as expected.

Examples of the Validate Script

Example 1: Validate a File by Applying a Custom Validation Scenario
sh scripts/validate.sh "workspace/xmlFolder/xmlFile.xml" -sn "xmlValScn" -sf "workspace/scn/valScn.scenarios"
This command implies validating xmlFile.xml by applying the validation scenario named xmlValScn, described in the valScn.scenarios file. If you want to apply more than one validation scenario, you can use the -sn scenarioName construct multiple times.
Example 2: Validate a Directory by Applying an Oxygen Default Validation Scenario
sh scripts/validate.sh "workspace/DITAFolder" -sn "DITA"
A scenario name is provided, but without specifying a scenarios file. This command implies validating all files from DITAFolder by applying the Oxygen default validation scenario named DITA (in accordance with the association made in the Document Type Configuration Dialog Box).
Example 3: Validate a File by Applying Associated Scenarios Stored in an Oxygen Project File
sh scripts/validate.sh "workspace/mainFolder/main.xml" -sf "worksapce/proj/proj-1.xpr"

A scenarios file is provided, but without specifying a scenario name. In this case, the argument provided through the -sf option is assumed to be an Oxygen project file and it is used to search for validation scenario associations made for the main.xml file. This command line implies that if validation scenario associations for main.xml are found in proj-1.xpr, then those scenarios are identified and applied. Otherwise, the validation first considers the schema associations declared in main.xml (if any), or default Oxygen validation scenarios are applied in accordance with the type of the file to validate (e.g. XML in this example).

Example 4: Directory Default Validation and Custom Formatted Report Saved to a Specific Location
sh scripts/validate.sh ../important/xmlFolder -rft html -rf "../important/reports/validation rep.html"

No validation scenario name, no scenario file, and no schema provided. This command line involves validating all files from the xmlFolder. Each file is validated against the schema(s) internally associated (if any). Otherwise, the default Oxygen validation scenarios for the respective file type are applied. Also, the validation report is formatted in HTML and is saved to the validation rep.html file at the specified location.

Figure 1. Example of an HTML Validation Report

Resources

For more information about the validation script, see the following resources:
Tip: For some GitHub use case samples of this script, see Oxygen Validation Template and Oxygen Validation Action.