Apigee OASValidation Policy Guidance for Nullable Types

Overview: Apigee OASValidation Policy and Nullable Types

The Apigee OASValidation policy is applied at runtime when an Apigee proxy bundle includes a request-validation.json or response-validation.json schema. This policy validates incoming requests or outgoing responses as they pass through the gateway (source: docs/apigee-oasvalidation-policy-guidance.md).

The SOAP-to-REST generator produces OpenAPI Specification (OAS) 3.0 schemas that use the nullable: true annotation. According to the OAS 3.0 specification, nullable: true is intended to widen the accepted type, allowing a JSON null value in addition to the base type (source: docs/apigee-oasvalidation-policy-guidance.md).

However, the Apigee OASValidation policy has historically shown inconsistent behavior in how it interprets nullable: true at runtime. This inconsistency means that even after a proxy bundle successfully saves, API publishers may encounter runtime validation rejections for fields with null values if their Apigee runtime exhibits this behavior (source: docs/apigee-oasvalidation-policy-guidance.md).

How OASValidation Handles Nullable Types

The core issue stems from how different Apigee hybrid and X releases interpret the nullable: true annotation at runtime (source: docs/apigee-oasvalidation-policy-guidance.md).

Two main behaviors have been observed:

• Ignoring nullable: true: In some Apigee releases, nullable: true is disregarded. The policy treats the field as strictly typed, leading to errors such as null found, string expected when a null payload value is encountered (source: docs/apigee-oasvalidation-policy-guidance.md).
• Adhering to OAS 3.0 specification: In other releases and configurations, the policy correctly accepts null values for fields marked nullable: true, matching the OAS 3.0 specification (source: docs/apigee-oasvalidation-policy-guidance.md).

This runtime inconsistency is a separate concern from bundle-save rejections. A previous fix (commit 2709282f) addressed bundle-save rejections by switching from OAS 3.1 "type": "null" literals to OAS 3.0 nullable: true, which Apigee's static validator accepts. The runtime behavior described here is an orthogonal issue (source: docs/apigee-oasvalidation-policy-guidance.md).

Guidance for API Publishers

API publishers have two primary paths to manage the OASValidation policy's behavior regarding nullable types (source: docs/apigee-oasvalidation-policy-guidance.md).

Path A: Disable the OASValidation Policy (Recommended)

The SOAP-to-REST runtime already performs validation of request and response payloads against configured conversion options and null-handling modes before data reaches the downstream SOAP service. Therefore, Apigee's OASValidation policy is often redundant, potentially adding latency and the risk of inconsistent null-handling without enhancing safety (source: docs/apigee-oasvalidation-policy-guidance.md).

How to disable:

1. Open the proxy bundle in the Apigee console or unzip the exported bundle archive. (source: docs/apigee-oasvalidation-policy-guidance.md)
2. In the relevant proxy or target endpoint flow that contains the OASValidation policy step, perform one of the following actions:
   • Set the policy's <Enabled> element to false.
   • Remove the <Step> element that references the OASValidation policy from the flow. (source: docs/apigee-oasvalidation-policy-guidance.md)
3. Save and deploy the revised bundle revision. (source: docs/apigee-oasvalidation-policy-guidance.md)

After disabling, null fields in requests and responses are validated exclusively by the SOAP-to-REST runtime, which consistently honors the API publisher's configured null-handling mode (source: docs/apigee-oasvalidation-policy-guidance.md).

Path B: Keep OASValidation with Lenient Validation

This path should only be used if Apigee policy-level enforcement is a strict requirement, such as for compliance rules mandating gateway-layer schema enforcement (source: docs/apigee-oasvalidation-policy-guidance.md).

Configuration:

1. In the OASValidation policy XML (e.g., apiproxy/policies/OASValidation-Request.xml), add or set <Options><Allow400/></Options>. (source: docs/apigee-oasvalidation-policy-guidance.md)
2. Configure the policy with strictMessageValidation set to false, if your Apigee version supports this flag. (source: docs/apigee-oasvalidation-policy-guidance.md)
3. Accept that nullable fields may still be rejected at the Apigee layer on some runtime versions. (source: docs/apigee-oasvalidation-policy-guidance.md)
4. As a fallback, widen the schema for the affected field by replacing nullable: true with a broader alternative type in the exported JSON schema. Do not use the OAS 3.1 "type": "null" literal, as this causes bundle-save rejections (source: docs/apigee-oasvalidation-policy-guidance.md).

Configuration Options for Lenient Validation

The following options can be configured within the OASValidation policy XML for lenient validation (source: docs/apigee-oasvalidation-policy-guidance.md).

| Name | Type | Default | Description | | <Options><Allow400/></Options> | N/A | N/A | When present, this option allows the OASValidation policy to return a 400 status code for validation failures, rather than a different error type. This can be useful for consistent error handling. (source: docs/apigee-oasvalidation-policy-guidance.md) | | strictMessageValidation | Boolean | N/A | If supported by the Apigee version, setting this flag to false can make the validation more lenient, potentially reducing rejections for nullable fields. (source: docs/apigee-oasvalidation-policy-guidance.md)

---

All SOAP-to-REST docs