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

Configuring the MessageValidation policy

Configure MessageValidation using the following elements.

The name attribute for this policy is restricted to these characters: A-Z0-9._\-$ %. However, the Management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Field Name Description
Source (Optional)
Source message to be validated.
  • If the source is missing, it is treated as a simple message. For example, <Source>message</Source>
  • 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.
ResourceURL (Optional)
XSD or WSDL file used in the schema validation against the source message. The message validation fails if the WSDL file does not have schemas or if the maximum import depth exceeds 10.
If ResourceURL 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
SOAPMessage (Optional)
Verifies that the message corresponds to the SOAP format of the specified version(s).
If the version attribute is not specified, the message could correspond to either SOAP 1.1 or 1.2 format (example below).
Element (Optional) Specifies the valid root elements.

Example - Message Validation policy

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

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

Policy schema

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

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)