p:validate-with-json-schema (3.1)

Validates a JSON document using JSON schema.

Summary
Description
- Validation parameters
Examples
- Basic usage (valid source document)
- Basic usage (invalid source document)
Additional details
Errors raised
Reference information

Summary

<p:declare-step type="p:validate-with-json-schema">
  <input port="source" primary="true" content-types="json" sequence="false"/>
  <output port="result" primary="true" content-types="json" sequence="false"/>
  <input port="schema" primary="false" content-types="json" sequence="false"/>
  <output port="report" primary="false" content-types="xml json" sequence="true"/>
  <option name="assert-valid" as="xs:boolean" required="false" select="true()"/>
  <option name="default-version" as="xs:string?" required="false" select="()"/>
  <option name="parameters" as="map(xs:QName,item()*)?" required="false" select="()"/>
  <option name="report-format" as="xs:string" required="false" select="'xvrl'"/>
</p:declare-step>

The p:validate-with-json-schema step validates the JSON document appearing on the source port using JSON Schema validation. The JSON schema (a JSON document itself) is supplied through the schema port. The result port emits a copy of the source document.

Ports:

Port	Type	Primary?	Content types	Seq?	Description
`source`	`input`	`true`	`json`	`false`	The document to validate.
`result`	`output`	`true`	`json`	`false`	A verbatim copy of the document that appeared on the `source` port.
`schema`	`input`	`false`	`json`	`false`	The JSON schema to validate against.
`report`	`output`	`false`	`xml json`	`true`	A report that describes the validation results, both for valid and invalid source documents. The format for this report is determined by the `report-format` option. When the `assert-valid` option is `true` and the document is invalid, nothing will appear on this port because error `XC0165` is raised.

Options:

Name	Type	Req?	Default	Description
`assert-valid`	`xs:boolean`	`false`	`true`	Determines what happens if the document is invalid: If `true`, error `XC0165` is raised. If `false`, the step always succeeds. The validity of the document must be determined by inspecting the document that appears on the `report` port.
`default-version`	`xs:string?`	`false`	`()`	Specifies the schema version if the schema itself doesn’t specify one itself. If both the schema doesn’t specify a version and this option is empty, the schema version is implementation-defined and therefore dependent on the XProc processor used.
`parameters`	`map(xs:QName,item()*)?`	`false`	`()`	Parameters controlling the validation. See Validation parameters for more information.
`report-format`	`xs:string`	`false`	`xvrl`	The format for the document on the `report` port. The value `xvrl` (default) will always work: the report will be in XVRL (Extensible Validation Report Language). Whether any other formats are supported is implementation-defined and therefore dependent on the XProc processor used.

Description

The p:validate-with-json-schema step applies JSON Schemavalidation to the JSON document appearing on the source port. The JSON schema is supplied using the schema port. The outcome of the step, what appears on the result port, is a verbatim copy of the source document.

Validation parameters

The p:validate-with-json-schema step has a parameters port of datatype map(xs:QName, item()*)?. This (optional) map passes additional parameters for the validation process to the step:

The parameters in this map, their values and semantics are implementation-defined and therefore dependent on the XProc processor used.
A special entry with key c:compile (the c namespace prefix is bound to the standard XProc namespace http://www.w3.org/ns/xproc-step) is reserved for parameters for the schema compilation (if applicable). The value of this key must be a map itself.
If the report-format option is set to xvrl (default): Any entries with keys in the xvrl namespace (http://www.xproc.org/ns/xvrl) are passed as parameters to the process that generates the XVRL report appearing on the report port. All standard XVRL generation parameters are supported.

Examples

Basic usage (valid source document)

Assume we have a JSON input document, called input-valid.json, that looks like this:

{
  "first_name": "Jane",
  "last_name": "Doe"
}

A JSON schema to validate this is as follows:

{
  "$id": "https://example.com/schemas/customer",
  "type": "object",
  "properties": {
    "first_name": {"type": "string"},
    "last_name": {"type": "string"},
    "email": {"type": "string"}
  },
  "required": [
    "first_name",
    "last_name"
  ]
}

Performing this validation using the p:validate-with-json-schema step returns the following on the report port:

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result" pipe="report@validate"/>

  <p:validate-with-json-schema name="validate">
    <p:with-input port="schema" href="example-json-schema.json"/>
  </p:validate-with-json-schema>

</p:declare-step>

Result document:

<report xmlns="http://www.xproc.org/ns/xvrl">
   <metadata>
      <timestamp>2025-02-06T10:45:02.99+01:00</timestamp>
      <document href="file:/…/…/input-valid.json"/>
      <schema href="file:/…/…/example-json-schema.json" schematypens="JsonSchema"/>
      <validator name="networknt/json-schema-validator"/>
   </metadata>
   <digest/>
</report>

Basic usage (invalid source document)

Using the same JSON schema as in Basic usage (valid source document), we’re now going to validate an invalid document (called input-invalid.json). Since we want to have a look at what comes out of the report port, we have to set the assert-valid option to false.

{"last_name": "Doe"}

Performing this validation using the p:validate-with-json-schema step returns the following on the report port:

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result" pipe="report@validate"/>

  <p:validate-with-json-schema assert-valid="false" name="validate">
    <p:with-input port="schema" href="example-json-schema.json"/>
  </p:validate-with-json-schema>

</p:declare-step>

Result document:

<report xmlns="http://www.xproc.org/ns/xvrl">
   <metadata>
      <timestamp>2025-02-06T10:45:03.25+01:00</timestamp>
      <document href="file:/…/…/input-invalid.json"/>
      <schema href="file:/…/…/example-json-schema.json" schematypens="JsonSchema"/>
      <validator name="networknt/json-schema-validator"/>
   </metadata>
   <detection severity="error" code="1028">
      <location jsonpath="$"/>
      <message>$.first_name: is missing but it is required</message>
   </detection>
   <digest/>
</report>

Additional details

p:validate-with-json-schema preserves all document-properties of the document appearing on its source port for the document on its result port.
The document appearing on the report port only has a content-type property. It has no other document-properties (also no base-uri).

Errors raised

Error code	Description
`XC0117`	It is a dynamic error if a report-format option was specified that the processor does not support.
`XC0163`	It is a dynamic error if the selected version is not supported.
`XC0164`	It is a dynamic error if the document supplied on `schema` port is not a valid JSON schema document in the selected version.
`XC0165`	It is a dynamic error if the `assert-valid` option on `<p:validate-with-json-schema>` is `true` and the input document is not valid.

Reference information

This description of the p:validate-with-json-schema step is for XProc version: 3.1. This is a non-required step (an XProc 3.1 processor does not have to support this).

The formal specification for the p:validate-with-json-schema step can be found here.

The p:validate-with-json-schema step is part of categories:

The p:validate-with-json-schema step is also present in version: 3.0.