Understanding xs:list in XML Schema

The xs:list element in an XML Schema Definition (XSD) is a simple type constructor used to define a data type that contains a whitespace-separated sequence of values. This article explores the core purpose of xs:list, how it derives new list types from existing atomic types, the standard facets used to constrain list items, and practical scenarios where list-based elements are beneficial.

What is xs:list?

In XML Schema, simple types are categorized as atomic, list, or union types. An atomic type holds a single value, such as a string, integer, or date. The purpose of the xs:list constructor is to create a list type composed of a series of atomic values separated by whitespace characters (spaces, tabs, and line feeds).

When an XML processor encounters an element or attribute defined with xs:list, it parses the content by tokenizing the string along whitespace boundaries and validates each individual token against the specified base type.

How to Define an xs:list

An xs:list can be declared in two main ways: by referencing an existing type using the itemType attribute or by embedding an anonymous xs:simpleType as a child element.

Using the itemType Attribute

You can reference built-in XSD types or user-defined types directly:

<xs:simpleType name="IntegerListType">
  <xs:list itemType="xs:integer"/>
</xs:simpleType>

In an XML instance document, the corresponding element would accept values such as:

<scores>10 25 80 45</scores>

Using an Anonymous Simple Type

If the list item requires custom restrictions, you can define an anonymous type within xs:list:

<xs:simpleType name="RGBListType">
  <xs:list>
    <xs:simpleType>
      <xs:restriction base="xs:integer">
        <xs:minInclusive value="0"/>
        <xs:maxInclusive value="255"/>
      </xs:restriction>
    </xs:simpleType>
  </xs:list>
</xs:simpleType>

Constraining List Types

Once a list type is created, it can be further constrained using xs:restriction and specific facets. These facets apply to the collection of items rather than the individual items themselves:

xs:length: Specifies the exact number of items permitted in the list.
xs:minLength: Defines the minimum number of items required.
xs:maxLength: Defines the maximum number of items allowed.
xs:enumeration: Defines allowed combinations of the entire list.
xs:pattern: Validates the whole serialized string using a regular expression.

For example, to enforce a coordinate system that requires exactly three float values (X, Y, and Z):

<xs:simpleType name="ThreeDCoordinates">
  <xs:restriction>
    <xs:simpleType>
      <xs:list itemType="xs:float"/>
    </xs:simpleType>
    <xs:length value="3"/>
  </xs:restriction>
</xs:simpleType>

Common Use Cases

Compact Data Representation: Storing vectors, matrices, or geographic coordinates without generating separate XML tags for each individual number.
Token Lists: Defining HTML-like multi-value attributes, such as class="btn primary large", where multiple string tokens are stored in a single attribute.
IDREFS and NMTOKENS: Supporting built-in XML list types such as xs:IDREFS, xs:NMTOKENS, and xs:ENTITIES, which are implemented natively as xs:list definitions over primitive types.