XML Schema (XSD): What It Is, How to Write One and Validate XML

The second row shows a document that parses without complaint and still fails: the XML is syntactically fine, and the schema says quantity is a whole number. For how XML compares with another common data format, see XML vs JSON.

XML Schema example: a purchase order, step by step

The pair at the top of the page is a small order. The structure follows the purchase order used in the Primer: a sequence of child elements, an optional comment element, a whole number with an upper limit. Reading the XSD from the top gives six steps.

1. The element named order is declared at the top level, so it is the only element that may start a document. Its type is a complex type, because it has child elements and an attribute.
2. Inside it, xs:sequence fixes the order of the children: customer, then quantity, then note.
3. The customer is a plain xs:string, one of the datatypes built into the language.
4. The quantity gets a type of its own: a restriction of xs:positiveInteger with the facet maxExclusive set to 100. Valid values are therefore the whole numbers from 1 to 99.
5. The note carries minOccurs="0", which makes it optional. The default for an element is exactly one occurrence.
6. The date is an attribute of type xs:date and is required, so an order without one is invalid.

Validation passes for the sample. Changing it breaks the document in specific ways, and a processor names each one. These messages came from xmllint with libxml 2.9.13; other processors and versions word them differently.

quantity is "five":
  Element 'quantity': 'five' is not a valid value of the local atomic type.

quantity is "100":
  Element 'quantity': [facet 'maxExclusive'] The value '100' must be less than '100'.

customer element removed:
  Element 'quantity': This element is not expected. Expected is ( customer ).

date is "14.03.2026":
  Element 'order', attribute 'date': '14.03.2026' is not a valid value of the atomic type 'xs:date'.

The sequence matters as much as the types. The schema lists customer before quantity, so a document with the two swapped is rejected even though each element on its own is fine. That strictness is useful for documents exchanged between systems, because both sides can rely on one order.

A value of 99 passes, and 0 fails because it is not a positive integer. Testing a boundary from both sides is the quickest way to confirm that a facet says what you meant.

How are elements, attributes and types declared?

An element declaration gives an XML element its name and type. A simple type describes atomic text values, lists or unions, and it constrains text or attribute values without child elements. A complex type describes child content and attributes, and it is the one that allows mixed content too. Types can be built in, named globally for reuse, or anonymous inside a declaration, as the quantity in the example is.

<xs:complexType name="ProductType">
  <xs:sequence>
    <xs:element name="name" type="xs:string"/>
    <xs:element name="price" type="xs:decimal"/>
  </xs:sequence>
  <xs:attribute name="sku" type="xs:string" use="required"/>
</xs:complexType>

A named type can be used by several elements, while an anonymous type belongs to the one declaration that contains it and cannot be referred to from elsewhere. Deciding whether identity or structure is the reusable concept is the subject of the guide to element references versus named types.

How do cardinality and value constraints work?

minOccurs and maxOccurs control how many times an element particle can occur. Simple-type facets constrain values with ranges, lengths, patterns and enumerations. In XSD 1.0 there are twelve facets in all, defined in Part 2 of the specification, and XSD 1.1 adds two. The enumeration facet limits a value to a fixed set, which suits a status code or a country list.

Patterns and enumerations answer different needs. An enumeration lists every allowed value, which fits a closed set that changes rarely. A pattern describes the shape of a value, such as a product code made of two letters and four digits, and accepts anything of that shape whether or not the product exists. Neither can look anything up elsewhere, so a schema can say that a code is well-formed and cannot say that it is in use.

Restrictions should reflect domain rules, and they should be tested with boundary examples. A limit of 99 that is wrong by one only surfaces when someone orders 100. The schema is a contract: values it forbids cannot enter the system through a validating interface, and values it allows must be ones the rest of the system can handle.

How do I create an XSD for an XML document?

1. Collect sample documents. Use real ones, not a single tidy example. Optional parts and repetitions only show up across several.
2. Fix the root element. Decide which element may start a document and declare it at the top level.
3. Derive the types. Elements with children get complex types, text-only elements get simple types, and structures that repeat get a named type.
4. Mark repetitions and optional parts. Set minOccurs and maxOccurs where the samples differ, and think about what the data can really do rather than what the samples happened to contain.
5. Add value limits. Use built-in datatypes first, then facets such as enumeration, pattern and ranges.
6. Validate and attack the result. Every sample must pass. Then write documents that should fail, such as a missing required element or a value just outside a limit, and confirm each one is rejected.

The order of work is deliberate. Types come before limits, because a limit only makes sense once the type is known, and limits come before validation, because a schema with no constraints accepts nearly anything and every test passes by default. The adversarial documents in the last step are what turn the schema from a description into a check.

Generators exist that infer a schema from sample documents. Their output is a draft: it reflects only what the samples contained, so the limits and the optional parts need the review above.

How do I validate XML against an XSD?

A validator takes two inputs, the instance document and the schema set, and reports either success or each violation. On the command line, xmllint does it in one call:

xmllint --noout --schema order.xsd order.xml
order.xml validates

For a document that does not conform, the same command lists the errors, as in the examples above. Running the formatter first is a quick way to find syntax problems: a document that is not well-formed never reaches the schema check, so those errors come first and the schema errors only after they are fixed.

When a document fails, the messages are read from the top. The first error often causes the later ones, as when a missing required element makes the validator complain about the next element in line. Fixing the first message and running the check again is faster than working through the whole list.

A document may point to its schema with xsi:schemaLocation or xsi:noNamespaceSchemaLocation. The specification describes these as hints about the physical location of schema documents. An application is free to ignore a hint and to take the schema from a source of its own. As an editorial reading, a hint inside a document is not a statement of trust: the schema should come from a controlled location, and a validator should not fetch it from whatever address an incoming document names.

How do include and import combine schema documents?

A vocabulary can span several schema documents, and one XML document can be validated against the whole set. xs:include combines documents for the same target namespace. A document that has no target namespace can be included too, and its declarations take on the namespace of the including schema. xs:import makes declarations from another namespace available. Relative locations, catalogs and resolver policies must work consistently in development, CI and production.

A production validator should load the complete schema set under an explicit resource policy. Avoid depending on uncontrolled remote network retrieval during validation. The behaviour is easy to test: in a trial with xmllint, an include whose target namespace differed from the including schema stopped with an error that named the difference.

What is XSD 1.1, and does XSD check business rules?

XSD 1.1 is a W3C Recommendation of 5 April 2012. Part 1 adds two features to the language: conditional type alternatives, where the type of an element is chosen by a test, and assertions, which attach conditions written with XPath to a type. Both are described in Part 1, in sections 3.12 and 3.13.

Processor support must be checked before a schema relies on them. In a trial, xmllint from libxml 2.9.13 could process only XSD 1.0 and refused to compile a schema that used xs:assert. A 1.1 schema therefore needs a processor that implements 1.1, and an example written for one should be run against such a processor before it is trusted.

As for business rules, XSD covers structure and datatypes well. A rule that compares two fields, such as an end date that must not precede a start date, is contextual. With version 1.1 it can be written as an assertion. Otherwise it needs a separate rule language or a validation layer in the application. XML representations of resources in an API can be described with XSD as well, and REST web services covers where schemas sit among the other contract formats.

Continue the learning path

1. Compare global and local XSD design patterns.
2. Apply the XML Schema best-practice checklist.
3. Learn rule-based validation with Schematron.
4. Plan compatible changes with the schema versioning guide.
5. Inspect a real XSD with the Pattern Analyzer.