Send Docs Feedback

SOAP Message Validation policy

  About | Samples | Element reference | Error codes | Schemas | Usage notesRelated topics


Validates a message against an XSD schema or WSDL definition and rejects the message if it does not conform.


This policy can be attached in the following locations. 

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
    PostFlow Flow PreFlow PostFlow Flow PreFlow    


<MessageValidation name="myPolicy">
   <SOAPMessage version="1.1/1.2"/>
   <Element namespace="">PurchaseOrder</Element>
   <Element namespace="">PurchaseOrder</Element>

Element reference

The element reference describes the elements and attributes of the MessageValidation policy.

<MessageValidation async="false" continueOnError="false" enabled="true" name="SOAP-Message-Validation-1">
   <DisplayName>SOAP Message Validation 1</DisplayName>
   <Element namespace="">SampleObject</Element>     

<MessageValidation> attributes

<MessageValidation async="false" continueOnError="false" enabled="true" name="SOAP-Message-Validation-1">
Attribute Description Default Presence

Set to true to specify that the policy should be run in a thread pool different than the pool servicing the request/response flow. Default is false.

Note: This setting is only used for for internal optimization. Contact Apigee support at the Support Portal for more information.

false Optional

Most policies are expected to return an error when a failure occurs. By setting this attribute to true, Flow execution continues on failure.

false Optional
enabled Determines whether a policy is enforced or not. If set to false, a policy is 'turned off', and not enforced (even though the policy remains attached to a Flow). true Optional

The internal name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Edge management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

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

N/A Required

<Source> element

Identifies the source message to be validated.

  • If you do not provide a <Source> value, a value of message is used.
  • If the <Source> variable cannot be resolved, or resolves to a non-message type, then one of the following occurs:
    • If the source variable resolves to a null value in the message flow, a steps.messagevalidation.SourceMessageNotAvailable error code is thrown.
    • If the source variable resolves to a non-message value, a steps.messagevalidation.NonMessageVariable error code is thrown.
Default: request
Presence: Optional
Type: String

<ResourceURL> element

Identifies the XSD schema or WSDL definition to be used to validate the source message.

If a <ResourceURL> value is not specified, the message is checked for:

  • Well-formed XML if the content-type is application/xml
  • Well-formed JSON if the content-type is application/json

If the WSDL does not have schemas or if the maximum import depth exceeds 10, message validation will fail.

Default: wsdl://<name>
Presence: Optional
Type: String

<SOAPMessage> element

Provides the SOAP version against which to validate SOAP messages.

<SOAPMessage version="1.1/1.2"/>
Default: N/A
Presence: Optional
Type: N/A


Attribute Description Default Valid values Presence

Identifies the SOAP version against which to validate SOAP messages.

  • 1.1
  • 1.2
  • 1.1/1.2

<Element> element

Specifies the root, or parent, element of the messages to be validated.

<Element namespace="">PurchaseOrder</Element>
<Element namespace="">PurchaseOrder</Element>
Default: sampleObject
Presence: Optional
Type: String


Attribute Description Default Presence

Provides the namespace of the root, or parent, element of the messages to be validated.

"" Optional

Error codes

The default format for error codes returned by policies is:

  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]

The MessageValidation policy type defines the following error codes:

Error Code Message
InvalidResourceType InvalidResourceType MessageValidation {0}: Invalid Resource Type {1}. It should be xsd or wsdl. Context {2}
ResourceCompileFailed ResourceCompileFailed MessageValidation {0}: Failed to compile resource {1}. Context {2}
RootElementNameUnspecified RootElementNameUnspecified MessageValidation {0}: RootElement name is not specified
InvalidRootElementName InvalidRootElementName MessageValidation {0}: RootElement name {1} is invalid
NonMessageVariable NonMessageVariable Variable {0} does not resolve to a Message
SourceMessageNotAvailable SourceMessageNotAvailable {0} message is not available for MessageValidation: {1}
NoElements Resource "{0}" has no element definitions
Failed MessageValidation {0} failed with reason: "{1}"


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

Usage notes

The MessageValidation Policy type enables you to configure API proxies to reject messages that do not conform to schema (.xsd) or WSDL definition(s). That means developers building apps to consume your API are immediately notified if they are submitting non-conformant requests. Message validation helps developers by indicating where XML tags may not be properly closed, for example. Validation also protects backend services by blocking XML or SOAP messages who structure might cause unpredictable behavior.

Validation can save you a call to tech support, and can help developers avoid time in the forums trying to find troubleshooting help. If developers are notified that they are submitting invalid requests, they can refer to the XML schema for the API to understand how to fix the error. This makes well-understood XML schemas a key component of your API documentation.

Apigee Edge enables you to configure your API with a MessageValidation policy that validates messages with the XML payload.

The policy validates that an XML or JSON message is well-formed, and that the SOAP format is correct according to the specified XSD or WSDL file, ensuring that tags are balanced. If the XML configuration is incomplete, the policy returns a message validation error.

Related topics

XML Threat Protection policy

XML to JSON policy

JSON to XML policy

JSON Threat Protection policy


Help or comments?

  • If something's not working: Ask the Apigee Community or see Apigee Support.
  • If something's wrong with the docs: Click Send Docs Feedback on this page.
    (Incorrect? Unclear? Broken link? Typo?)