XSD nillable vs minOccurs: three kinds of nothing

Presence and value are separate decisions. minOccurs controls whether an element must occur. nillable controls whether it may carry xsi:nil="true". Its datatype determines whether ordinary empty content is valid. See the W3C explanation of nil values.

Try missing, empty, nil and a value

Start with an optional string. The empty element passes. Switch the datatype to integer and the same empty element fails. Now allow nil and select the explicit nil instance: the element passes again, for a different reason.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="record">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="value" type="xs:string"
          minOccurs="0" nillable="false"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

<record xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <value/>
</record>

The complete presence-and-nil matrix

This table fixes the datatype at unrestricted xs:string. Each row tests the same four instances. It is a reference you can read or print without operating the experiment.

For xs:integer, every ordinary empty case fails. For a string restricted with minLength="1", ordinary empty content also fails. Those are value constraints; they do not turn a missing element into a present one. W3C datatype reference.

Choose what each state means to your application

Imagine an import carrying a customer’s middle name. Your application might interpret absence as “leave the stored value unchanged,” explicit nil as “clear the stored value,” and an empty string as a value to reject. Those meanings belong in the interface contract. The schema does not invent them for you.

Write one example for each accepted operation before choosing the declaration. Then check the deserialized result as well as the validator result. A binding library that maps both missing and nilled input to the same language value can erase a distinction that your update operation needs.

For a required numeric measurement, consider whether a missing reading is represented by an explicit nil value or whether an incomplete record should be rejected. Pair the chosen representation with a documented reason field if consumers need to distinguish “not measured” from “sensor error.”

Download a reproducible example

The experiment emits a complete schema and XML document. Save both downloads in one folder and validate the current case with an XSD 1.0 processor. For example, with libxml2 installed:

xmllint --noout --schema nillable-example.xsd nillable-example.xml

Change one control, save a second fixture, and record why its result should differ. In a production test, also assert the value your consumer receives. These examples have no default or fixed values, custom facets, attributes on the value element or surrounding choice groups; introduce those features as separate tests.

Next, compare sequence, choice and all to see how the containing group changes what may appear. Use the element-versus-type guide when deciding whether to share a declaration or just its value rules.