00:00:08This video offers a demonstration of using scripts
from a command-line tool to validate documents.
00:00:15The "validate" script is located in
the Oxygen installation directory,
00:00:19inside the "scripts" folder, along with
the other supported scripts. And for
00:00:24the purposes of this demonstration,
I've added a folder named "work-spc"
00:00:28inside that "scripts" folder and it
contains the sample files I'll use.
00:00:34In my command line window, I've already
navigated to the "scripts" folder. The
00:00:39script I'm demonstrating is "validate" and I can
use the help option to display details about the
00:00:45script and it's supported options. The first
option is the only mandatory one. It specifies
00:00:51the path to the file or directory to validate.
And then you see that there are various optional
00:00:57arguments and there's some additional
notes to help you with some of them.
00:01:01I'll start by using the script in its
most simple form. I only specified the
00:01:06path to a directory within my sample folder.
I didn't specify a schema to validate against,
00:01:11or a validation scenario to apply, and no other
optional arguments. It simply instructing the
00:01:17engine to use the default settings to validate
all of the files in the specified folder.
00:01:23After I execute the command and after the
validation completes, you see that a report
00:01:27is displayed in the console. I'll scroll up
and then back down just to show you that it
00:01:34lists details for each problem, including
information about the file, the schema,
00:01:38scenario name, the type of document,
description of the problem, and more.
00:01:44That report was displayed in the default text
format, but you can use the -rft argument to
00:01:49display the report in XML, JSON, or HTML
format. I chose xml for this next example
00:01:58and you can see that the report is now
in xml format without indentation.
00:02:04Of course, it would be easier to read
and work with if it were opened in a
00:02:08specialized xml editor. So, instead
of displaying it in the console,
00:02:12I'll use the -rf option to send the results
to an xml file located in a specified path.
00:02:19Then I can locate that xml file in the folder I
specified and open it in Oxygen's specialized xml
00:02:26editor. And I'll click the Format and Indent
toolbar button to make it look nicer.
00:02:31To make the report even easier to read,
using the html format might be better. So,
00:02:38I'll specify html for the -rft option and the
path for an html file using the -rf option.
00:02:48Then I'll locate that HTML file and open
in my default browser. There is a summary
00:02:54at the beginning. Then each validation problem
that was found is listed, grouped by file, with
00:02:59information such as a description of the problem,
its severity, the name of the validation engine,
00:03:04the scenario name, and the location of the
problem within the validated document.
00:03:10Next, I'll use the -s option to
specify the path to a schema to
00:03:14validate a specific JSON document against.
00:03:18I'll open this report in the browser. It found 4
problems and this time you see that it lists the
00:03:24schema file that was used in the validation.
If you want to use more than one schema to
00:03:29validate against within a single script, you
can configure a validation scenario in Oxygen
00:03:34with multiple validation units. You can see
that I have already configured one called
00:03:39"library" and it has 2 validation units (one for
a JSON schema and one for a Schematron schema).
00:03:46Once configured, then you would go to Options
and select "Export Global Validation Scenarios",
00:03:53save it. Then you can reference the
exported scenarios file in the script.
00:04:00Back in the command line, I'll display the help
page again, and I'll be using the -sn and -sf
00:04:06options to specify the name of the validation
scenario and the path to the scenarios file.
00:04:12My command would look like this ... and
I'll open this report file in the browser.
00:04:21This time it found 5 problems instead of
4. I'll scroll down and you can see that in
00:04:26addition to the problems found by the "JSON
Validator" engine, there's also a problem
00:04:31that was found by the Schematron engine.
You can also use the -sn option without specifying
00:04:38a scenarios file. This particular use-case is
explained in the notes in the help page.
00:04:46In this case, it searches through the validation
scenarios defined in the associations made in
00:04:51Oxygen's Document Type Association dialog box.
For example, if I want to validate DITA files by
00:04:57applying the default validation scenario
defined for this type of document...
00:05:01I would specify DITA using the -sn option
(without also using the -sf option)...
00:05:08I'll open that report in the browser, and you
can see that the engine name is DITA Validation,
00:05:13the scenario name is DITA, and
the document type is DITA 2.x.
00:05:20Along with Oxygen's default scenarios associated
through the Document Type Associations,
00:05:25you can also add custom ones that you can use in
the script. In this next example of a command,
00:05:31I specify 3 scenarios, the default DITA scenario,
along with 2 custom ones named "DITA-sch" and
00:05:38"DITA-tab" that would be associated with the DITA
file type in the doc type association dialog box.
00:05:45I won't execute the command because those
associations don't exist (I'm just showing you as
00:05:51an example), but it would apply all 3 scenarios to
validate the files in the specified folder.
00:05:57Conversely, you can specify the path to a
validation scenarios file using the -sf option
00:06:04without using the -sn option to specify a scenario
name. So, in my next example, I specify a DITA
00:06:12file named "main.dita" as the file to validate,
and I use the -sf option to specify the path to
00:06:19a project file with an xpr file extension.
Now, if validation scenario associations for
00:06:25that specified file are found in the xpr file,
then those scenarios are applied. Otherwise, the
00:06:30validation first considers the schema associations
declared directly in the file (if any exist),
00:06:36or default Oxygen validation scenarios are
applied in accordance with the document type.
00:06:41I'll open the resulting report in the
browser, and you can see the name of
00:06:45the scenario that was applied and the
schema that was validated against.
00:06:51I'll go back to the help page because I want to
point out that there are some filtering options
00:06:55that can be applied. The -if option can be used to
only validate the files that match the specified
00:07:01pattern, the -ef option can be used to exclude
files that match the specified pattern, and the
00:07:07-ed option can be used to exclude sub-directories
that match the specified pattern.
00:07:13So, I'll enter a command that validates a specific
JSON file against a specific JSON schema file.
00:07:20I'll open the report in the browser.
00:07:23Note that the first problem is reported for a
JSON file that contains a "draft" string.
00:07:30If I scroll down, you can see that the last
reported issue was due to the fact that a
00:07:34Schematron file was validated against a JSON
schema file, which doesn't make much sense.
00:07:41So, I use a similar command but this time
I'll include some filtering options.
00:07:46I'll use the -if option to only validate JSON
files ... the -ef option to exclude the file
00:07:53with the draft string ... and the -ed option
to exclude a particular sub-directory.
00:08:01I'll locate the report and open it in my
browser ... and if I compare this report
00:08:07side-by-side with the previous one, you
see that this newer one has now filtered
00:08:11out some of the problems according to the
filtering options I used in the script.
00:08:16This concludes this demonstration
about the validate script.
00:08:19 Thank you for watching and we welcome you to
please subscribe to our various channels.