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, policy available from V2018.4.1.0 2.0.0

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.
  • wsdl: 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.
 string

You can also apply a validate policy by using the API Manager 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'