Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 36 ยท WSDL and Contracts

XML Schema Types for WSDL

Learn the XML Schema parts a WSDL uses: built-in types, simple types with facets, complex types, minOccurs and maxOccurs, nillable and enumerations, and validate messages in code.

A WSDL tells you which operations exist. The XML Schema (XSD) inside its types section tells you exactly what the data looks like: which fields, which types, which are optional, which values are legal. A SOAP message that does not match the schema is invalid, and good services reject it before running any business code. Understanding XSD also lets you predict what Java classes or C# types a code generator will create.

Built-in types

XSD ships with dozens of built-in simple types, prefixed xsd: (the namespace http://www.w3.org/2001/XMLSchema). These cover most needs:

XSD type Example value Typical language type
xsd:string Tea string
xsd:int, xsd:long, xsd:short 42 int, long, short
xsd:integer 123456789012345678901 big integer
xsd:decimal 19.99 BigDecimal, decimal
xsd:double, xsd:float 3.14e0 double, float
xsd:boolean true, false, 1, 0 boolean
xsd:date 2026-11-12 date
xsd:dateTime 2026-11-12T09:30:00Z timestamp
xsd:base64Binary SGVsbG8= byte array
xsd:anyURI https://example.org URI

Use decimal for money (never double), and dateTime with a time zone for moments in time.

Simple types and facets

You make your own simple type by restricting a built-in type with facets:

XML
<xsd:simpleType name="Quantity">
  <xsd:restriction base="xsd:int">
    <xsd:minInclusive value="1"/>
    <xsd:maxInclusive value="100"/>
  </xsd:restriction>
</xsd:simpleType>

<xsd:simpleType name="Currency">
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="EUR"/>
    <xsd:enumeration value="USD"/>
    <xsd:enumeration value="GBP"/>
  </xsd:restriction>
</xsd:simpleType>

<xsd:simpleType name="Sku">
  <xsd:restriction base="xsd:string">
    <xsd:pattern value="[A-Z]{1,3}-[0-9]{3}"/>
    <xsd:maxLength value="7"/>
  </xsd:restriction>
</xsd:simpleType>

Common facets: minLength, maxLength, length, pattern (regular expression), enumeration, minInclusive, maxInclusive, totalDigits, fractionDigits. Code generators turn an enumeration into a Java enum or a C# enum.

Complex types and elements

A complex type describes an element that has children or attributes. The usual content model is a sequence: children in a fixed order.

XML
<xsd:complexType name="OrderLine">
  <xsd:sequence>
    <xsd:element name="sku" type="tns:Sku"/>
    <xsd:element name="quantity" type="tns:Quantity"/>
    <xsd:element name="note" type="xsd:string" minOccurs="0"/>
  </xsd:sequence>
  <xsd:attribute name="id" type="xsd:int" use="required"/>
</xsd:complexType>

<xsd:element name="PlaceOrder">
  <xsd:complexType>
    <xsd:sequence>
      <xsd:element name="customer" type="xsd:string"/>
      <xsd:element name="line" type="tns:OrderLine" maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:element>

Important knobs:

  • minOccurs / maxOccurs (default 1 and 1). minOccurs="0" makes a field optional; maxOccurs="unbounded" makes it a list.
  • sequence (ordered), all (any order, each at most once), choice (exactly one of several).
  • nillable="true" lets an element be present but empty with xsi:nil="true", meaning "null". This differs from minOccurs="0", which means "absent".
  • elementFormDefault="qualified" on the schema means local elements must be in the target namespace; with unqualified (the default) they must have no namespace. Mismatching this with the message is a classic validation error.
  • Extension (xsd:extension) and restriction create inheritance; xsi:type in a message picks a subtype at runtime.

Validating values by type

Schema validation is mostly checks like these. The next program implements the main built-in types and facets from the lists above, then runs a few values through them.

Node.js Simple-type validation

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.

Validating a whole message

Real validators also check structure: required children present, order, counts, no unknown elements. This second program reads a schema description (built from the sequence in an XSD, written here as data) and validates an OrderLine instance.

Node.js Checking children, order and occurrences

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.

Schema habits that save pain

  • Prefer elements to attributes for data; use attributes for identifiers and metadata. Elements extend more easily.
  • Name types and reuse them. Anonymous inline types make ugly generated classes.
  • Make optional things minOccurs="0" and document what absence means. Avoid inventing magic values such as -1.
  • Never remove or rename elements in a published schema. Add new optional elements instead; clients written for the old version keep working.
  • Use decimal for money and dateTime with zone for instants.
  • Restrict early. A tight pattern or enumeration rejects bad data at the edge.

Validation against the schema is separate from business validation. The schema says an order line has a positive quantity; it cannot know whether the SKU exists in your catalog. Do both.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which XSD type should hold a price such as 19.99?

    decimal is exact; double and float can introduce rounding errors in money.
  2. 2. What does minOccurs="0" on an element mean?

    minOccurs=0 makes the element optional. Nillable is a different feature: the element is present but null.
  3. 3. How do you let an element be present but carry no value (null)?

    A nillable element can appear with xsi:nil="true".
  4. 4. Which compatibility rule is safest when evolving a published schema?

    Adding optional elements keeps old clients valid. Renaming or removing breaks them.

Summary

  • The types section of a WSDL uses XML Schema to define every element and type in the messages.
  • Built-in types cover strings, numbers, dates and binary; facets restrict them into your own types.
  • Complex types combine elements with sequence, all or choice, minOccurs/maxOccurs and attributes.
  • Optional (minOccurs=0) and null (nillable) are different ideas.
  • Evolve schemas by adding optional parts, never by renaming or removing.

Next: WSDL Bindings, Ports and Messages in Detail