VideosValidating XML and JSON using Oxygen XML Editor Command Line Scripts


Duration: 08:27

This video shows how to use scripts from a command-line tool to validate documents.


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.

Use Oxygen Feedback to ask us anything about this video.