NOTE: Some aspects of this product are in Beta. The hybrid installation options are GA. To join the Beta program, reach out to your Apigee representative.

OASValidation policy

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 (JSON or YAML). 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 must have a .json, .yml, .yaml extension.

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

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.
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.

Schemas

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 500 Request 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.NotMessageVariable 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.

Variables Where Example
fault.name="fault_name" fault_name is 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"
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

Related topics