Validate JSON Schema Assertion (Threat Protection)

The Validate JSON Schema assertion validates JSON (JavaScript Object Notation) data against a JSON schema.
Specifically, the assertion 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.
2
Context Variable
This assertion populates the following variable:
Variable
Description
jsonscheme.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 and it maintains compatibility with previous versions of this assertion.
  • true: The assertion fails and a warning is logged.
(1) The "strict mode" setting has effect only if $schema property is present in the JSON schema. (2) The "strict mode" setting only comes into play during run time. If a version mismatch can be detected during design time, you are prompted to correct immediately. For details, see 'Run Time vs. Design Time' below.
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 json. schemaVersionStrict.enabled cluster property
Assertion Properties
Setting
What You Should Know...
Target Message
Specify the target message to be validated:
  • Request: Validate the request message. This is the default setting if the assertion is positioned before the routing assertion in the policy.
  • Response: Validate the response message. This is the default setting if the assertion is positioned after the routing assertion in the policy.
  • Other Variable: Validate the JSON content stored in a context variable. This variable is typically 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 before the Validate JSON Schema assertion.
You can also set the message target outside of the assertion. For more information, see Select a Target Message.
Schema Location
Indicate where the schema is located:
  • Configure in advance: You are defining the JSON schema directly, using one of the following methods:
    • Type or paste the code into the Validation Schema box. You may reference context variables. The assertion checks the input for correct JSON structure, but does not validate any of the variables entered.
      You need to 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 using [Read 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 using [Read File]. Review the content of the Validation Schema box and edit if necessary.
  • Monitor URL for latest value: The Gateway monitors a URL that you enter for changes. You may reference context variables in the URL. By default, the Gateway issues an If-Modified-Since: HTTP request for this URL approximately every 5 minutes while the schema is in use.
    (1) 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. (2) The monitor time interval is controlled by the json. schemaCache.maxAge cluster property.
  • Retrieve Schema URL from Content-Type or Link Header: 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 URL 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-schema
    Example of a "describedby" HTTP header:
    Link: <http://json.com/my-hyper-schema>; rel="describedby"
    • Use [Add] to add as many regular expressions as necessary to determine if a URL belongs to the set of white-listed URLs.
    • Use [Edit] to modify any of the regular expressions.
    • Use [Delete] to remove a regular expression from the list.
    • Select the Skip validation... check box to allow the assertion to succeed if no schema URL is present in the message. Clear this check box to always check for a schema URL (the assertion fails if not found).
Schema Version
Select the JSON schema version to validate against.
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.
Frequently Asked Questions
Question
Answer
How large can the JSON schema be?
The schema maximum size is controlled by the schemacache. maxSchemaSize cluster property.
Are external URLs supported?
No, external URLs referenced using the $ref element in JSON Schema V4 are not supported.
Are hyper-schemas supported?
No, hyper-schemas are currently not supported.
Which audits should I look for when using this assertion?
This assertion logs the following audits during validation: 9130, 9131, 9132, 9134. For details, see Audit Detail Codes.
Are other versions of the JSON Schema supported?
No, this assertion only supports JSON Schema V2 or V4. Version V3 or any of the more recent versions (V5, V6) are not supported.