You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/reference/policies/oas-validation-policy). info
![](https://docs.apigee.com/static/api-platform/images/icon_policy_mediation.jpg)

## 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?](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#what-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](https://docs.apigee.com/api-platform/develop/resource-files).

> [!NOTE]
> **Note:** You can store the OpenAPI Specification with the API proxy revision only. See [Where resources are stored](https://docs.apigee.com/api-platform/develop/resource-files#stored).

## 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>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#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>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#allowunspecified) |


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>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#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>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#displayname) [`<OASResource>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#oasresource) [`<Source>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#source) [`<Options>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#options) [`<Source>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#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>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#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** | \<<var translate="no">PolicyElement</var>\> |
| **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](https://docs.apigee.com/api-platform/develop/resource-files).


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](https://docs.apigee.com/api-platform/reference/message-template-intro).

|---|---|
| **Default Value** | None |
| **Required?** | Required |
| **Type** | String |
| **Parent Element** | [`<OASValidation>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#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>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#oasvalidation) |
| **Child Elements** | [`<ValidateMessageBody>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#validatemessagebody) [`<AllowUnspecifiedParameters>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#allowunspecified) |

#### 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>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#oasvalidation)
element to **true**.

> [!NOTE]
> **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 succeed automatically (without actually validating the content).

|---|---|
| **Default Value** | false |
| **Required?** | Optional |
| **Type** | Boolean |
| **Parent Element** | [`<Options>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#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>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#options) |
| **Child Elements** | [`<Header>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#header) [`<Query>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#query) [`<Cookie>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#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>
```

**`<Header>` (child of `<AllowUnspecifiedParameters>`)**

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>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#allowunspecified) |
| **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>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#allowunspecified) |
| **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>
```

**`<Cookie>` (child of `<AllowUnspecifiedParameters>`)**

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>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#allowunspecified) |
| **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>`](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#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](https://github.com/apigee/api-platform-samples/tree/master/schemas/policy)
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 Edge 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](https://docs.apigee.com/api-platform/fundamentals/what-you-need-know-about-policy-errors) and [Handling
faults](https://docs.apigee.com/api-platform/fundamentals/fault-handling).

### Runtime errors

These errors can occur when the policy executes.

> [!IMPORTANT]
> **Tip:** Use [API Monitoring](https://docs.apigee.com/api-monitoring) to investigate fault codes and diagnose issues faster. See [Set up a policy fault code alert](https://docs.apigee.com/api-monitoring/alerts-notifications#fault-code-alert) for an example. See [Fault code reference](https://docs.apigee.com/api-monitoring/fault-codes) for a complete list of all fault codes that you can handle with API Monitoring.

| 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](https://docs.apigee.com/api-platform/reference/variables-reference#message). | [](https://docs.apigee.com/api-platform/troubleshoot/policies/runtime/assign-message-runtime-errors#unresolvedvariable) |

### 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](https://docs.apigee.com/api-platform/fundamentals/what-you-need-know-about-policy-errors).

| Variables | Where | Example |
|---|---|---|
| `fault.name="fault_name"` | <var translate="no">fault_name</var> is the name of the fault, as listed in the [Runtime errors](https://docs.apigee.com/api-platform/reference/policies/oas-validation-policy#runtime-errors) table above. The fault name is the last part of the fault code. | `fault.name Matches "ResourceDoesNotExist"` |
| `oasvalidation.policy_name.failed` | <var translate="no">policy_name</var> is the user-specified name of the policy that threw the fault. | `oasvalidation.myoaspolicy.failed = true` |

<br />

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

> [!NOTE]
> **Note:** The OASValidation policy will reject OpenAPI Specifications that use unsupported features. In this case, the policy will not pass the validation of the unsupported features and deployment of the API proxy fails.

| 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`) <br /> **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

- [JSON Threat
  Protection policy](https://docs.apigee.com/api-platform/reference/policies/json-threat-protection-policy)
- [SOAPMessageValidation policy](https://docs.apigee.com/api-platform/reference/policies/message-validation-policy)