DataPower API Gateway

validate - DataPower API Gateway

Use the validate policy to validate the payload in an assembly flow against a schema.

Gateway support

Note: This page describes the validate policy implementation in the DataPower® API Gateway. If you are using the DataPower Gateway (v5 compatible), see validate - DataPower Gateway (v5 compatible).

For information on the different types of gateway, see API Connect gateway types.

Table 1. Table showing which gateways support this policy, and the corresponding policy version
Gateway Policy version
DataPower API Gateway 2.0.0

2.1.0 (DataPower API Gateway Version 10.0.1.0 or later)

2.2.0 (DataPower API Gateway Version 10.0.2.0 or later)

2.3.0 (DataPower API Gateway Version 10.0.2.0 or later)

2.4.0 (DataPower API Gateway Version 10.0.4.0 or later)

2.5.0 (DataPower API Gateway Version 10.5.0.0 or later)

2.6.0 (DataPower API Gateway Version 10.5.0.2 or later

2.7.0 (DataPower API Gateway Version 10.5.0.3 or later

This topic describes how to configure the policy in your OpenAPI source; for details on how to configure the policy in the assembly user interface, see Validate - DataPower API Gateway.

About

The validate policy has the following format:
- validate:
    version: version
    title: title
    description: description
    validate-against: validation_mechanism
         .
         .
         .
       properties_specific_to_the specified_validation_mechanism
         .
         .
         .

Apply this policy by adding an assembly extension with an execute field to your OpenAPI definition file.

Note: With the DataPower API Gateway, the input to the validate policy must be parsed data. One way to produce parsed data is to use a parse policy before a validate policy in your assembly flow, which provides explicit control of the parse action.

Properties

The following table describes the policy properties:
Table 2. validate policy properties
Property Required Description Data type
version Yes The policy version number string
title No A title for the policy. string
description No A policy description. string
input No Identifies a variable in the API context. The content of the body field of the variable, which is represented by variable_name.body, is the input data to validate. By default, the variable name is message. string
output No Specifies the name of a variable in the API context.
  • If the validation passes, the body field of the output variable, which is represented by variable_name.body, stores the output of the assembly validate action.
  • If the schema to validate is a JSON schema, the validation also adds any default values that are missing from the payload.
  • If the validation fails, no output is stored.
  • If an output variable is not specified, the results of the assembly validate action are not saved.
 string
validate-against Yes Specifies the schema to be used for validating the payload.
Valid values:
  • definition: A previously defined schema will be used to validate the payload that is returned from other invoke actions or tasks in the assembly flow.

    In addition, supply a definition property to specify the required schema.

  • url: the schema is identified by a URL location.
    In addition, supply the following properties:
    • json-schema field: the URL of the JSON schema to be used for validating a JSON payload.
    • xml-validation-mode, specify one of the following values to define how an XML payload is validated:
      • xsd: use an XML schema; in addition, supply an xml-schema property that specifies the URL of the XML schema.
      • wsdl: use a WSDL schema; in addition, supply an xml-schema property that specifies the URL of the WSDL schema to be used for validating a SOAP payload..
      • soap-body: validate the body of a SOAP message against the XML schema only.
      Note: The following limitations apply to schemas used for JSON validation, which include JSON schemas and OpenAPI documents that are used as schemas for validation. Exceeding these limits can impact compilation performance and is not supported.
      • Maximum of 6,500 lines. Each key and each item in an array count as a line.
      • Maximum recursion depth of 250.
      • Maximum of 3,000 items in enum lists.
  • wsdl: (use with a SOAP service based API only) use the XML schema in the WSDL file associated with the API operation or the API path.
  • body-param: validate the request input against the schema definition that is specified in the schema property for the request parameter for this operation.
  • response-param: validate the response to be returned to the client application, against the schema definition that is specified in the schema property for the response parameter for this operation.
  • graphql: (use with a GraphQL proxy API only) validate the payload against the GraphQL schema that has been imported into the GraphQL proxy API. In addition, either the GraphQL query or response, depending on the input, is analyzed against the GraphQL schema to calculate the cost, and the result is placed in the API context.

    For more information on GraphQL proxy APIs, see Creating a GraphQL proxy API and GraphQL context variables.

    .
 string
xslt-version No The XSLT processor version. The default value is XSLT10. string
strict No Whether to enable strict XSLT error checking. Non-strict operations attempt to recover from certain errors, such as use of undeclared variables, calling undeclared templates, and so forth. By default, strict XSLT error checking is enabled. boolean
profile No Whether to enable stylesheet profiling. This option should not be used in production environments. By default, stylesheet profiling is disabled. boolean
debug No Whether to run the stylesheet, XQuery script, and JSONiq script in debug mode. When a stylesheet, XQuery script, or JSONiq script is run in debug mode, it generates a custom web page instead of displaying its normal output. The web page details exactly what occurred during execution, including the values of variables and where particular pieces of the output came from. This option should not be used in production environments. By default, debug mode is disabled. boolean
stream No Whether the stylesheet must be run in streaming mode. Transformation of the document begins before the input is fully parsed. Not all stylesheets can be streamed. If the stylesheet cannot be streamed, an error is generated and the input is not processed. By default, streaming mode is disabled. boolean
try-stream No Whether to attempt to run the stylesheet in streaming mode. Transformation of the document begins before the input is fully parsed. Not all stylesheets can be streamed. If the stylesheet cannot be streamed, a warning is generated during compilation and the stylesheet is read in the entire input as normal at execution time. By default, attempting to run the stylesheet in streaming mode is disabled. boolean
minimum-escaping No Whether to escape output produced from the stylesheet during processing. Minimal escaping is particularly useful when handling non-English character sets. By default, minimum escaping is disabled. boolean
stack-size No The maximum number of bytes that the stack is allowed to use while executing a stylesheet or other compiled content. This setting is used to block infinite recursion. The minimum value is 10 kilobytes, or 10,240 bytes. The maximum value is 100 megabytes, or 104,857,600 bytes. The default value is 1 megabyte, or 1,048,576 bytes. integer
wsi-validation No The validation behavior to apply to WSDL files that are checked for conformance to section 5 of WS-I Basic Profile (version 1.0, April 2004). The default setting is Warn.
Ignore
Disables conformance checking.
Warn
Logs warnings for violations.
Fail
Forces conformance. Fails if the file contains any violation.
 string
wsdl-validate-body No The validation behavior for the soap:Body. The default setting is Strict.
Strict
Validates this part of the message against the WSDL definition. Allows only messages that contain this part and that match the WSDL definition.
Lax
Validates this part of the message against the WSDL definition. If the message contains this part and the WSDL definition does not define this part, allow the message. If the message contains this part and the WSDL definition defines this part, allow the message only when there is a match.
Skip
Disables validation of this part of the message.
 string
wsdl-validate-headers No

The validation behavior for the soap:Header. The default setting is Lax.

Strict
Validates this part of the message against the WSDL definition. Allows only messages that contain this part and that match the WSDL definition.
Lax
Validates this part of the message against the WSDL definition. If the message contains this part and the WSDL definition does not define this part, allow the message. If the message contains this part and the WSDL definition defines this part, allow the message only when there is a match.
Skip
Disables validation of this part of the message.
 string
wsdl-validate-faults No Specifies the validation behavior for the fault detail. The default setting is Strict.
Strict
Validates this part of the message against the WSDL definition. Allows only messages that contain this part and that match the WSDL definition.
Lax
Validates this part of the message against the WSDL definition. If the message contains this part and the WSDL definition does not define this part, allow the message. If the message contains this part and the WSDL definition defines this part, allow the message only when there is a match.
Skip
Disables validation of this part of the message.
 string
wsdl-wrapped-faults No Whether to require compatibility with RPC-style wrappers. By default, RPC-style wrappers are not required. boolean
allow-soap-enc-array No Whether to allow the schema to accept most uses of elements with xsi:type='SOAP-ENC:Array' consistent with SOAP 1.1 Section 5, even when these attributes violate the XML Schema specification. Normally, the xsi:type attribute must name a type equal to or derived from the actual type of the element. For schemas compiled with this option, xsi:type is accepted specifically for the SOAP 1.1 Encoding 'Array' complex type if the element type is derived from SOAP-ENC:Array. The opposite is the normal allowable case. By default, elements with xsi:type='SOAP-ENC:Array' are not accepted. boolean
validate-soap-enc-array No Whether to perform extra schema validation following the encoding rules in SOAP 1.1 Section 5. When enabled, members of SOAP arrays are validated, attributes such as @id and @href are allowed even if they are not allowed by the schema, and @href values are checked to ensure that they have a corresponding @id element. By default, the extra validation is not performed. boolean
wildcards-ignore-xsi-type No Whether xs:any elements in the schema validate only child elements by name. The XML Schema specification requires that, if a wildcard matches an element but that element does not have an element declaration, the element is instead validated according to an xsi:type attribute on it. This option ignores those xsi:type attributes. It should be used for cases such as SOAP envelope validation where a further validation step will validate the contents matching the wildcard, possibly using the SOAP 1.1 encoding rules. By default, xsi:type attributes are not ignored. boolean
wsdl-strict-soap-version No Whether to strictly follow the SOAP binding in the WSDL. When enabled, only messages bound to SOAP 1.2 appear in SOAP 1.2 envelopes and only messages bound to SOAP 1.1 appear in SOAP 1.1 envelopes. By default, strict SOAP binding is disabled. boolean
xacml-debug No Whether to compile XACML policies with debug information. Note that the XACML debugging messages are also controlled by the log event in the XACML category. Use the debug log level to view the full XACML debugging messages. By default, XACML policies are not compiled with debug information. boolean
allow-xop-include No Specifies whether the schema or WSDL document accepts messages where base64-encoded binary content was optimized according to the MTOM/XOP specifications. XOP binary-optimization replaces base64-encoded binary data with an xop:Include reference element that references the unencoded binary data located in an attachment. By default, MTOM/XOP optimized messages are disabled.
  • When disabled, such optimized messages are rejected by validation of the optimized form. Rejection occurs because the schema specifies a simple type that accepts base64-encoded data, such as xs:base64Binary or xs:string, but the message contains an xop:Include element instead.
  • When enabled, an xop:Include element can optionally appear in place of content for any XML Schema simple type that validates base64-encoded binary data. The xop:Include element itself will be validated according to the built-in schema in store:///schemas/xop.xsd.
 boolean

You can also apply a validate policy by using the API Designer assembly editor to add a built-in policy to the API. For more information, see Validate - DataPower API Gateway in the built-in policies section.

Example 1

- validate:
    version: 2.0.0
    title: 'validate, response parameter schema'
    validate-against: response-param

Example 2

- validate:
    version: 2.0.0
    title: 'validate, predefined schema'
    validate-against: definition
    definition: '#/definitions/RouteOutput'

Example 3

- validate:
    version: 2.0.0
    title: 'validate, JSON and XML schema URLs'
    validate-against: url
    json-schema: 'https://my.json.schema'
    xml-validation-mode: xsd
    xml-schema: 'https://my.xml.schema'