Send Docs Feedback

SOAP Message Validation policy

What

Validates a message and rejects it if it does not conform to the specified requirements. Use this policy to: 

  • Validate any XML message against an XSD schema.
  • Validate SOAP messages against a WSDL definition.
  • Confirm JSON or XML is well-formed, based on content-type (if <ResourceURL> element is omitted)

Where

This policy can be attached in the following locations. 

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Samples

<MessageValidation name="myPolicy">
   <Source>mymessage</Source>
   <ResourceURL>xsd://sample</ResourceURL>
   <SOAPMessage version="1.1/1.2"/>
   <Element namespace="http://finance.com/1999">PurchaseOrder</Element>
   <Element namespace="http://finance.com/2000">PurchaseOrder</Element>
</MessageValidation>

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="http://sample.com">SampleObject</Element>     
   <SOAPMessage/>     
   <Source>request</Source>     
   <ResourceURL>wsdl://SOAP-Message-Validation-1</ResourceURL>
</MessageValidation>

<MessageValidation> attributes

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

The following attributes are common to all policy parent elements.

Attribute Description Default Presence
name

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
continueOnError

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.

false Optional
enabled

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.

true Optional
async

This attribute is deprecated.

false Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default:

N/A

If you omit this element, the the value of the policy's name attribute is used.

Presence: Optional
Type: String

 

<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.
<Source>mymessage</Source>
Default: request
Presence: Optional
Type: String

<ResourceURL> element

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

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

If a <ResourceURL> value is not specified, the message is checked for well-formed JSON or XML if the content-type is application/json or application/xml, respectively.

<ResourceURL>xsd://sample</ResourceURL>
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

Attributes

Attribute Description Default Valid values Presence
version

Identifies the SOAP version against which to validate SOAP messages.

None
  • 1.1
  • 1.2
  • 1.1/1.2
Optional

<Element> element

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

<Element namespace="http://finance.com/1999">PurchaseOrder</Element>
<Element namespace="http://finance.com/2000">PurchaseOrder</Element>
Default: sampleObject
Presence: Optional
Type: String

Attributes

Attribute Description Default Presence
namespace

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

"http://sample.com" Optional

Error codes

Errors returned from Edge policies follow a consistent format as described in the Error code reference.

This policy returns the following error codes and error messages in error responses. For guidance on handling errors, see Fault handling

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

Schemas

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

Usage notes

The SOAPMessageValidation Policy type enables you to configure API proxies to: 

  • Validate any XML message against an XSD schema.
  • Validate SOAP messages against a WSDL definition.
  • Confirm JSON or XML is well-formed, based on content type (if <ResourceURL> element is omitted)

When an XML file to be validated contains references to external schemas, you must use the xsd prefix when specifying the schema location. For example:

<xs:include schemaLocation="xsd://mySchema.xsd"/>

Messages that do not conform to the specified requirements are rejected. Message validation provides the following benefits:

  • Immediately notifies app developers that are consuming your API if their requests are non-conformant or incomplete.
  • Provides information to help developers pinpoint issues in their requests, such as XML tags that are not properly closed.
  • Blocks XML or SOAP messages with structures that might cause unpredictable behavior, protecting backend services.
  • Minimizes time spent troubleshooting, searching forums, or consulting with tech support.
  • Encourages developers to familiarize themselves with the XML schema WSDL definition to eliminate validation errors, making well-understood XML schemas a key component of your API documentation.

Related topics

XML Threat Protection policy

XML to JSON policy

JSON to XML policy

JSON Threat Protection policy

 

Help or comments?