Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 36 ยท Testing and Tools

Contract Validation and Schema Checks

Keep a SOAP service honest against its contract - understand what XSD validation checks, write a mini validator for order, types and facets, and detect drift between a WSDL and the code behind it.

A WSDL is more than documentation. It is a contract that says "these operations exist, and the messages look like this". The moment the code and the contract disagree, partners start to fail in ways that are hard to explain: a field that used to be optional is now required, a new element appears in the middle of a sequence, a number comes back as 12,5.

Contract testing means checking, automatically, that messages and implementation match the contract. In this lesson you will learn what XML Schema (XSD) validation actually checks, build a small validator to see it work, and then write a drift detector that compares an operation list with the code that serves it.

What XSD validation checks

The schema inside a WSDL describes each message element. Validation covers:

  • Structure: which child elements appear, in which order (xsd:sequence), how many times (minOccurs, maxOccurs), and whether unknown elements are allowed.
  • Types: xsd:int, xsd:decimal, xsd:boolean, xsd:date (2026-11-12), xsd:dateTime, xsd:string.
  • Facets: restrictions such as maxLength, pattern, minInclusive, or an enumeration of allowed values.
  • Namespaces: elements must be in the target namespace the schema declares.

A snippet of a schema for an order request (read-only):

XML
<xsd:element name="PlaceOrder">
  <xsd:complexType>
    <xsd:sequence>
      <xsd:element name="sku"      type="xsd:string"/>
      <xsd:element name="quantity" type="xsd:int"/>
      <xsd:element name="coupon"   type="xsd:string" minOccurs="0"/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:element>

On a real system you validate with a proper library or command, for example xmllint --noout --schema order.xsd message.xml, Java's javax.xml.validation (jakarta has the same API), or .NET's XmlReaderSettings with a schema set. They also resolve imports and all of XSD's features, which our mini validator does not.

A mini validator

This validator understands a simplified schema: a list of child elements with a type, whether it is optional, and optional facets. It checks order, unknown elements, missing required elements and values. It reuses the compact XML reader from the earlier server lesson.

Node.js Validate messages against a contract

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice how the "wrong order" message produces errors even though it has all the right elements: in an xsd:sequence, order is part of the contract. This surprises developers who think of XML like JSON, where key order does not matter. A strict partner service will reject exactly this message.

Detecting drift

Drift happens when the WSDL says one thing and the running code does another: an operation was added in code but not in the contract (partners cannot use it) or an operation was removed from code but is still advertised (partners get faults). A cheap, powerful test compares two lists.

Node.js Contract drift detector

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Run this check in your continuous integration pipeline, and the contract can never silently diverge. A related practice is a breaking-change check: compare the new WSDL with the last released one and fail the build if a required element was added, an element was removed or renamed, or a type was narrowed. Adding an optional element at the end of a sequence is normally a safe change.

Validate incoming requests against the schema in your service (reject early with a Client fault that names the failing element) and validate outgoing responses in tests. Validating responses in production is usually too expensive, but in tests it catches mistakes before partners do.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In an xsd:sequence, what happens if elements appear in a different order than declared?

    A sequence defines an ordered list. A strict validator rejects the same elements in the wrong order.
  2. 2. Which is usually a backward-compatible change to a response message?

    Existing clients ignore or tolerate a new trailing optional element; renames, removals and type changes break them.
  3. 3. What does a facet like xsd:pattern or xsd:enumeration do?

    Facets narrow a base type: allowed patterns, lengths, ranges or a fixed list of values.
  4. 4. What does a drift detector compare?

    It reports operations or parameters present on only one side, so the contract stays truthful.

Summary

  • XSD validation checks structure, order, cardinality, types, facets and namespaces.
  • Validate requests early and give precise Client faults; validate responses in tests.
  • Drift detection compares the WSDL's operations with the implementation and fails the build on differences.
  • Treat breaking changes (renames, removals, type changes, new required elements) as new versions.

Next: Migrating SOAP Services to REST