Validate JSON Schema Assertion (Message Validation/Transformation)

The Validate JSON Schema assertion is used to validate JSON (JavaScript Object Notation) data against a JSON schema.
Beginning with Gateway version 10.0 CR1, JSON Schema v2 has been deprecated due to a library upgrade. Users should upgrade their JSON Schema to v4.
The Validate JSON Schema assertion validates JSON (JavaScript Object Notation) data against a JSON schema. Specifically it will:
  • Validate JSON data structure
  • Validate JSON data property types
  • Validate JSON data property values
You can specify the JSON Schema Version (v2 or v4) to verify the payload against. If the JSON schema specifies a version that differs from the assertion properties, the
json.schemaVersionStrict.enabled
cluster property indicates which takes precedence.
The JSON schema can either be defined within the assertion, or retrieved from a URL, or extracted from a Content-Type or Link header.
Place a Protect Against JSON Document Structure Assertion before this assertion to protect against DOS attacks.
If a JSON schema contains an invalid keyword, it is ignored and no error is logged.
Context Variables
This assertion populates the following variable:
Variable
Description
jsonschema.failure
Returns the JSON schema validation error.
Cluster Properties
This assertion is affected by the following cluster properties. Restart the Gateway for changes to take effect.
Property
Description
json.schemaCache.maxAge
Maximum age of a cached JSON schema. Default:
300000
(milliseconds)
json.schemaCache.maxDownloadSize
Maximum size of a downloaded JSON schema. Enter zero for an unlimited size.
Default: value from the ${documentDownload.maxSize} variable,
10485760
bytes default
json.schemaCache.maxEntries
Maximum number of cached schemas. Enter zero to disable caching. Default:
100
json.schemaCache.maxStaleAge
Maximum age of expired cached JSON schema documents that are loaded from URLs. A setting of "-1" indicates no expiry. Default:
-1
(milliseconds)
json. schemaVersionStrict.enabled
The JSON schema version is specified in the assertion properties. It may also be specified by the $schema property in a JSON Schema V4. This cluster property determines what happens when a version mismatch is discovered during run time:
  • false
    . The JSON schema version that is specified in the assertion properties is used. The version mismatch is logged. This is the default setting that maintains compatibility with previous versions of this assertion.
  • true
    . The assertion fails and a warning is triggered.
The "strict mode" setting has effect only if $schema property is present in the JSON schema.
The "strict mode" setting only applies to run time. If a version mismatch is detected during design time, you are prompted to correct it immediately.
Run Time vs Design Time
The Validate Against JSON Schema assertion lets you specify the schema location. If you choose "Configure in advance", the assertion can detect mismatches in the JSON schema version during design time. Should this occur, you must correct the mismatch before exiting the assertion properties. The
json.schemaVersionStrict.enabled
cluster property is not used in this scenario.
If you select one of the other schema location settings ("Monitor URL for latest value" or "Retrieve Schema URL from Content-Type or Link Header"), the JSON schema version is not known until run time. How the assertion responds during a mismatch is determined by the js
on.schemaVersionStrict.enabled
cluster property.
Using this Assertion
Configure the assertion properties when you initially add the assertion to a policy. Modify existing properties by double-clicking the assertion in a policy.
Specify the target message to be validated:
  • Request
    : Select this to validate the request message. This is the default setting if the assertion is positioned before the routing assertion in the policy.
  • Response
    : Select this to validate the response message. This is the default setting if the assertion is positioned after the routing assertion in the policy.
  • Other Variable
    : Select this to validate JSON content stored in a context variable. This variable will normally be either a String or a Message variable with Content-Type 'application/json' or another Content-Type that allows text. This variable must be predefined or has been set in the policy prior to the Validate JSON Schema assertion. For more information on Message variables, see Context Variables.
You can also set the message target outside of the assertion. For more information, see Select a Target Message.
Specify the schema location:
Indicate where the schema is located.
Configure in advance
Use one of the following techniques:
  • Manually type or paste the code into the
    Validation Schema
    box. Variables may be used. The assertion checks the input for correct JSON structure, but does not validate any of the variables entered. You can use the ".mainpart" suffix on variables of type Message and with Content-Type 'application/json'. For more information about this suffix, see "Context Variable Data Types" under Context Variables.
  • Load the schema from a URL by clicking
    Read URL
    and then specifying the URL.  Review the content of the
    Validation Schema
    box and edit if necessary. To configure options for the URL (for example, to specify the credentials, SSL, or proxy options), click
    HTTP Options
    to open the Manage HTTP Options dialog.
  • Load the schema from a local file by clicking
    Read File
    and then browsing to the appropriate file. The schema maximum size is controlled by the schemacache.maxSchemaSize cluster property.
Monitor URL for latest value
The
Layer7 API Gateway
monitors a URL that you enter for changes. The URL may contain context variables that will be resolved at run time. By default,
Layer7 API Gateway
will issue an
If-Modified-Since:
HTTP request for this URL approximately every 5 minutes while the schema is in use.
To configure options for the URL (for example, to specify the credentials, SSL, or proxy options), click
HTTP Options
to open the Manage HTTP Options dialog. The monitor time interval is controlled by the json. schemaCache.maxAge cluster property.
Retrieve Schema URL from Content- Type or Link Header
Select this option to retrieve the JSON schema URL from either a Content-Type profile parameter in the header or from a Link header.
If there exists a "Content-Type header and a Link header, both with varying schema locations, the Content-Type schema URL location takes precedence.
Example of a MIME type parameter: 'profile':Content-Type: application/json; profile=http://json.com/my-hyper-schemaExample of a "describedby" HTTP header:Link: <http://json.com/my-hyper-schema>; rel="describedby"
  • Click
    Add
    to add as many regular expressions as necessary to determine if a URL belongs to the set of white-listed URLs.
  • Click
    Edit
    to modify any of the regular expressions.
  • Click
    Delete
    to remove a regular expression from the list.
  • Select the
    Skip validation...
    check box to allow the assertion to succeed if there is no schema URL in the message. Clear this check box to always check for a schema URL (the assertion will fail if not found).
The Content-Type parameter is checked first; if a URL is not found, then the header values are checked.
Specify the schema version
Select either
JSON Schema Draft v2
or
JSON Schema Draft v4
. These versions refer to the JSON Schema specification IETF Internet-Drafts.For more details, see https://json-schema.org/specification-links.html.
By default, the schema version you choose here is always used, regardless of any version specified in the schema. However, if the
json.schemaVersionStrict.enabled
cluster property is set to true, the assertion fails if the schema indicates a version that differs from what is set here.