OASValidation policy

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

policy icon

About the OASValidation policy

The OASValidation (OpenAPI Specification Validation) policy enables you to validate an incoming request or response message against an OpenAPI 3.0 Specification, using JSON or YAML format. See What content is validated?

The OASValidation policy specifies the name of the OpenAPI Specification to use for validation when the step to which the policy is attached executes. The OpenAPI Specification is stored as a resource in the following standard location within the API proxy bundle: apiproxy/resources/oas. The OpenAPI Specification document must have a .json, .yml, or .yaml extension.

Add an OpenAPI Specification as a resource to an API proxy bundle using the UI or API, as described in Manage resources.

This policy is a Standard policy and can be deployed to any environment type. For information on policy types and availability with each environment type, see Policy types.

What content is validated?

The following table summarizes the request message content that is validated by the OASValidation policy, by component.

Components Request validation
Basepath Validates the basepath defined by the API proxy; ignores the basepath specified in the OpenAPI Specification.
Path Validates that the request path (minus the basepath) matches one of the path patterns defined in the OpenAPI Specification.
Verb Validates that the verb is defined for the path in the OpenAPI Specification.
Request message body
  • Validates the existence of the message body in the request, if required.
  • Optionally, validates the message body against the operation's request body schema in the OpenAPI Specification. Configure this option using <ValidateMessageBody>

Note: The policy validates a request message body against the OpenAPI Specification only if the Content-Type is set to application/json. If the content type is not set to application/json, the request message body validation will pass automatically (without actually validating the content).

Parameters
  • Validates that the required parameters are present in the request, including path, header, query and cookie parameters.
  • Validates that the parameter values match those defined in the OpenAPI Specification.
  • Optionally, validates whether parameters exist in the request that are not defined in the OpenAPI Specification. Configure this option using <AllowUnspecifiedParameters>

The following table summarizes the response message content that is validated by the OASValidation policy, by component.

Components Response validation
Path Validates that the request path (minus the basepath) matches one of the path patterns defined in the OpenAPI Specification.
Verb Validates that the verb is defined for the path in the OpenAPI Specification.
Response message body
  • Validates the existence of the message body in the response, if required.
  • Validates that the response headers in the OpenAPI Specification are present in the response message, and that the value of the response headers matches the schema.
  • Optionally, validates the message body against the operation's response body schema in the OpenAPI Specification. Configure this option using <ValidateMessageBody>

Samples

The following examples show some of the ways in which you can use the OASValidation policy to validate messages against an OpenAPI 3.0 Specification.

Validate request message

In the following example, the myoaspolicy policy validates the body of the request message against the operation's request message body schema defined in the my-spec.json OpenAPI Specification.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.json</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
   <Source>request</Source>
</OASValidation>

If the message body doesn't conform to the OpenAPI Specification, a policies.oasvalidation.Failed error is returned.

Validate parameters

The following example configures the policy to fail if a header, query, or cookie parameters is specified in the request that is not defined in the OpenAPI Specification.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<OASValidation> element

Defines the OpenAPI Specification Validation policy.

Default Value See Default Policy tab below
Required? Required
Type Complex object
Parent Element n/a
Child Elements <DisplayName>
<OASResource>
<Source>
<Options>
<Source>

Syntax

The <OASValidation> element uses the following syntax:

<OASValidation
  continueOnError="[true|false]"
  enabled="[true|false]"
  name="policy_name"
>
    <!-- All OASValidation child elements are optional except OASResource -->
    <DisplayName>policy_display_name</DisplayName>
    <OASResource>validation_JSON_or_YAML</OASResource>
    <Options>
        <ValidateMessageBody>[true|false]</ValidateMessageBody>
        <AllowUnspecifiedParameters>
            <Header>[true|false]</Header>
            <Query>[true|false]</Query>
            <Cookie>[true|false]</Cookie>
        </AllowUnspecifiedParameters>
    </Options>
    <Source>message_to_validate</Source>
</OASValidation>

Default Policy

The following example shows the default settings when you add an OAS Validation policy to your flow in the Apigee UI:

<OASValidation continueOnError="false" enabled="true" name="OpenAPI-Spec-Validation-1">
    <DisplayName>OpenAPI Spec Validation-1</DisplayName>
    <Properties/>
    <Source>request</Source>
    <OASResource>oas://OpenAPI-Spec-Validation-1.yaml</OASResource>
</OASValidation>

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

continueOnError false Optional Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also:
enabled true Optional Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

Child element reference

This section describes the child elements of <OASValidation>.

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value N/A
Required? Optional. If you omit <DisplayName>, the value of the policy's name attribute is used.
Type String
Parent Element <PolicyElement>
Child Elements None

The <DisplayName> element uses the following syntax:

Syntax

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Example

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

The <DisplayName> element has no attributes or child elements.

<OASResource>

Specifies the OpenAPI Specification to validate against. You can store this file:

  • At the API proxy scope under /apiproxy/resources/oas in the API proxy bundle
  • In the Resources section of the API proxy editor's Navigator view.

For more information, see Manage resources.

You can specify the OpenAPI Specification using a message template, such as {oas.resource.url}. In this case, the value of flow variable oas.resource.url (in curly braces) will be evaluated and substituted into the payload string at runtime. For more information, see Message templates.

Default Value None
Required? Required
Type String
Parent Element <OASValidation>
Child Elements None

Syntax

The <OASResource> element uses the following syntax:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   ...
</OASValidation>

Example

The following example references the my-spec.yaml specification that is stored under /apiproxy/resources/oas in the API proxy bundle:

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
</OASValidation>

The <OASResource> element has no attributes or child elements.

<Options>

Configures options for the policy.

Default Value n/a
Required? Optional
Type Complex type
Parent Element <OASValidation>
Child Elements <ValidateMessageBody>
<AllowUnspecifiedParameters>

Syntax

The <Options> element uses the following syntax:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <ValidateMessageBody>[true|false]</ValidateMessageBody>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
         <Query>[true|false]</Query>
         <Cookie>[true|false]</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Example

The following example configures the options for the policy. Each of the options are described in more detail below.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <ValidateMessageBody>false</ValidateMessageBody>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<ValidateMessageBody>

Specifies whether the policy should validate the message body against the operation's request body schema in the OpenAPI Specification. Set to true to validate the message body contents. Set to false to validate only that the message body exists.

You can control whether flow execution continues following a validation error by setting the continueOnError attribute for the <OASValidation> element to true.

Default Value false
Required? Optional
Type Boolean
Parent Element <Options>
Child Elements None

Syntax

The <ValidateMessageBody> element uses the following syntax:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
         <ValidateMessageBody>[true|false]</ValidateMessageBody>
   </Options>
   ...
</OASValidation>

Example

The following example enables the validation of the message body contents:

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
</OASValidation>

<AllowUnspecifiedParameters>

Configures the behavior of the policy if there are header, query, or cookie parameters present in the request that are not defined in the OpenAPI Specification.

Default Value n/a
Required? Optional
Type Complex type
Parent Element <Options>
Child Elements <Header>
<Query>
<Cookie>

Syntax

The <AllowUnspecifiedParameters> element uses the following syntax:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
         <Query>[true|false]</Query>
         <Cookie>[true|false]</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Example

The following example configures the policy to fail if a header, query, or cookie parameters is specified in the request that is not defined in the OpenAPI Specification.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

Configures the behavior of the policy if there are header parameters present in the request that are not defined in the OpenAPI Specification.

To allow header parameters to be specified in the request that are not defined in the OpenAPI Specification, set this parameter to true. Otherwise, set this parameter to false to cause policy execution to fail.

Default Value true
Required? Boolean
Type Complex type
Parent Element <AllowUnspecifiedParameters>
Child Elements None

Syntax

The <Header> element uses the following syntax:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Example

The following example configures the policy to fail if a header parameter is specified in the request that is not defined in the OpenAPI Specification.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Query> (child of <AllowUnspecifiedParameters>)

Configures the behavior of the policy if there are query parameters present in the request that are not defined in the OpenAPI Specification.

To allow query parameters to be specified in the request that are not defined in the OpenAPI Specification, set this parameter to true. Otherwise, set this parameter to false to cause policy execution to fail.

Default Value true
Required? Boolean
Type Complex type
Parent Element <AllowUnspecifiedParameters>
Child Elements None

Syntax

The <Query> element uses the following syntax:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Example

The following example configures the policy to fail if a query parameter is specified in the request that is not defined in the OpenAPI Specification.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>false</Query>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

Configures the behavior of the policy if there are cookie parameters present in the request that are not defined in the OpenAPI Specification.

To allow cookie parameters to be specified in the request that are not defined in the OpenAPI Specification, set this parameter to true. Otherwise, set this parameter to false to cause policy execution to fail.

Default Value true
Required? Boolean
Type Complex type
Parent Element <AllowUnspecifiedParameters>
Child Elements None

Syntax

The <Cookie> element uses the following syntax:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Example

The following example configures the policy to fail if a query parameter is specified in the request that is not defined in the OpenAPI Specification.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Source>

JSON message to be evaluated against JSON payload attacks. This is most commonly set to request, as you will typically need to evaluate inbound requests from client apps. Set to response to evaluate response messages. Set to message to automatically evaluate the request message when the policy is attached to the request flow and the response message when the policy is attached to the response flow.

Default Value request
Required? Optional
Type String
Parent Element <Source>
Child Elements None

Syntax

The <Source> element uses the following syntax:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Source>[message|request|response]</Source>
   ...
</OASValidation>

Example

The following example evaluates automatically the request message when the policy is attached to the request flow and the response message when the policy is attached to the response flow:

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Source>message</Source>
</OASValidation>

The <Source> element has no attributes or child elements.

Schema for this policy

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

Error codes

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause
steps.oasvalidation.Failed 400 The Request message body cannot be validated against the provided OpenAPI Specification.
steps.oasvalidation.Failed 500 The Response message body cannot be validated against the provided OpenAPI Specification.
steps.oasvalidation.SourceMessageNotAvailable 500

Variable specified in the <Source> element of the policy is either out of scope or cannot be resolved.

steps.oasvalidation.NonMessageVariable 500

<Source> element is set to a variable that is not of type message.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause
ResourceDoesNotExist OpenAPI Specification referenced in the <OASResource> element does not exist.
ResourceCompileFailed OpenAPI Specification that is included in the deployment contains errors that prevent it from being compiled. This generally indicates that the specification is not a well-formed OpenAPI Specification 3.0.
BadResourceURL OpenAPI Specification referenced in the <OASResource> element cannot be processed. This can occur if the file is not a JSON or YAML file or the file URL is not specified correctly.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variable Description Example
fault.category The category of the fault. When the policy rejects a request, this will always hold Step. fault.category = "Step"
fault.name The name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "ResourceDoesNotExist"
fault.reason The reason for the fault. It is a human-readable string explaining the reason for the fault. OASValidation OAS-1 with resource "oas://my-spec1.yaml": failed with reason: "[ERROR - POST operation not allowed on path '/persons/13'.: []]"
fault.subcategory The subcategory of the fault. When the policy rejects a request, this will always hold OASValidationFailure. fault.subcategory = "OASValidationFailure"
OASValidation.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. OASValidation.myoaspolicy.failed = true

Supported OpenAPI Specifications features

The OASValidation policy supports the OpenAPI Specification features that are summarized in the following table, by category. The features that are not supported are also listed.

Category Supported Not supported
Data type formats boolean
date
date-time
double
email
float
int32/int64
ipv4/ipv6
md5
sha1/sha256/sha512
string
uri
uri-template
uuid
binary
byte
password
Discriminator object mapping
propertyName
N/A
Media type object schema encoding
example
examples
Operations object parameters
requestBody
responses
security (partial support)
callbacks
deprecated
servers
Parameters object allowEmptyValue
in (query, header, path)
required
responses
schema
style (deepObject, form, formmatrix, label, pipeDelimited, simple, spaceDelimited)

Note: deepObject supports string parameters only; arrays and nested objects are not supported.
allowReserved
deprecated
example
examples
content
Paths object delete
get
head
options
parameters
patch
post
put
trace
variables
servers
Request body object application/json
application/hal+json
application/x-www-form-urlencoded (encoding object not supported)
content
required
application/xml
multipart/form-data
text/plain
text/xml
Response object application/json
application/hal+json
application/x-www-form-urlencoded (encoding object not supported)
content
headers
application/xml
links
text/plain
text/xml
Responses object default
HTTP Status Code
N/A
Schema object $ref
additionalProperties (boolean flag variant only)
allOf (ignored if additionalProperties is false)
anyOf
enum
exclusiveMaximum/exclusiveMinimum
format
items
maximum/minimum
maxItems/minItems
maxLength/minLength
maxProperties/minProperties
multipleOf
not
nullable
oneOf
pattern
properties
required
title
type
uniqueItems
deprecated
example
readOnly
writeOnly
xml
Security scheme object in (header, query) (ignored if type is http)
name
type (apiKey, http)
bearerFormat
flows
openIdConnectUrl
scheme
Server object url
variables
Multiple server definitions

Using patterns in schema

The OpenAPI Specification standard allows specifications to stipulate a schema to describe the data type of a parameter or field. For a parameter or field of type string, the schema may also define a pattern, which is a regular expression (regex) that defines valid forms for the string.

As an example, consider the following OpenAPI Specification fragment:

paths:
  /products/{product-id}:
    get:
      operationId: getProduct
      summary: Get product by id
      description: returns information regarding a product, by id
      parameters:
        - name: product-id
          in: path
          description: id of the product
          required: true
          schema:
            type: string
            pattern: '^\w{3}-\d{4}$'

This specification requires that for the getProduct operation, the product-id parameter should comply with the given regex, which stipulates a sequence of 3 word characters, a dash, and 4 decimal digits.

The OpenAPI Specification defers to the JSON Schema Validation standard for formally defining the behavior of the pattern in validating the string value, and to the JSON Schema Core standard for recommendations to schema authors regarding the restricted set of regular expression syntax. That latter standard recommends avoiding the use of lookarounds (lookaheads and lookbehinds), backreferences, and octal character expressions, among other features, within patterns inside OpenAPI Specification documents.

By default, Apigee validates the OpenAPI Specification document referenced by the OASValidation policy and reports errors if the specification document is not well formed. Apigee also validates regex patterns in your specification document and reports problems found there.

It is important to note that if you employ regex features outside of the recommended subset, Apigee will not validate the regex and will suspend any additional validation of your OpenAPI Specification document. If there is an error in the document, or in the regex that uses a feature outside the recommended subset, or if the regex feature is not supported by the Apigee runtime, the error will be detected only at runtime when the policy executes.

The following table provides some examples.

Pattern Behavior
^\w{3}-\d{4}$

The pattern is valid. It uses only regex features within the recommended subset. Apigee will allow save or import of the proxy, and at runtime the OASValidation policy will work as intended, validating the parameter against the pattern.

^([a-z]\w{3}-\d{4}$

The pattern is invalid; it is missing a closing parenthesis. The pattern does not use regex features outside the recommended subset. Apigee will report this error at the time you import or save your API proxy.

^(?![a-z]\w{3}-\d{4}$

The pattern is invalid. As with the prior example, it is missing a closing parenthesis. But Apigee will not report this error at the time you save or import your API Proxy, because the regex is using a negative lookahead, which is outside the recommended subset of regex features. The error will be detected only at runtime when the policy executes.

^(?![a-z])\w{3}-\d{4}$

The pattern is valid, but it uses a negative lookahead, which is outside the recommended subset of regex features. Apigee will suspend validation of the OpenAPI Specification document. At runtime, when you execute the OASValidation policy that references a specification using this pattern, because the Apigee runtime actually supports negative lookaheads, Apigee will correctly apply this regex to validate the parameter value.

^(a)?b(?(1)c|d)$

The pattern is valid, but uses a capturing group conditional, which is outside the recommended subset of regex features. Apigee will suspend validation of the OpenAPI Specification document. At runtime, when you execute the OASValidation policy that references a specification using this pattern, because the Apigee runtime does not support this regex feature, Apigee will return an error.

We recommend using only the recommended subset of features in your regex to prevent runtime failures.

Related topics