OASValidation policy

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

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.

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

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.

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

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

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

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

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.

The <DisplayName> element uses the following syntax:

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<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 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 and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

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

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.

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.

Related topics

• JSON Threat Protection policy
• SOAPMessageValidation policy