HowToCodePage

XML Schema and data types in messages

The WSDL types section is an XSD schema, and the mapping between XSD and language types is where precision and nullability are lost.

The mapping table

XSD typeJavaC#Trap
xsd:stringStringstringUnicode; length limits only if you add facets
xsd:intintintOverflow is a fault, not a truncation
xsd:longlonglongJavaScript clients lose precision above 2^53
xsd:decimalBigDecimaldecimalNever map money to a floating point type
xsd:dateTimeXMLGregorianCalendarDateTimeTime zone is often omitted and then assumed
xsd:booleanbooleanboolOnly true, false, 1, 0 are valid
xsd:base64Binarybyte[]byte[]33 percent size overhead inline
xsd:any / anyTypeObjectobjectSchema validation is disabled for that part
<xs:element name="Order">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="sku" type="xs:string" minOccurs="1"/>
      <xs:element name="note" type="xs:string" minOccurs="0" nillable="true"/>
      <xs:element name="qty" type="xs:int" minOccurs="0" default="1"/>
      <xs:element name="price" type="xs:decimal"/>
      <xs:element name="placedAt" type="xs:dateTime"/>
      <xs:element name="lines" type="xs:complexType" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="line" type="xs:string" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
</xs:element>

Missing, empty and nil

<!-- Three different meanings, and code that conflates them is wrong -->
<Order>
  <sku>A-1</sku>
  <!-- note is absent: minOccurs=0, so the element may not appear at all -->
  <!-- qty absent: the schema default of 1 applies -->
</Order>

<Order>
  <sku>A-1</sku>
  <note></note>   <!-- empty string, which is present and not nil -->
  <qty>0</qty>
</Order>

<Order>
  <sku>A-1</sku>
  <note xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
</Order>
  • An absent optional element, an empty element and a nil element are three distinct states. Map them to three distinct values or document which two you collapse together.
  • In Java, generated clients give you a isSetNote() style accessor when the schema is optional — use it instead of testing for null.
  • A schema default applies only when the element is absent, not when it is present and empty.
  • choice means exactly one of the alternatives; generated code exposes them as sibling fields and no validation forces you to set one.
  • Repeated elements become arrays or lists, and an empty list usually serialises as no elements at all rather than an empty container.
💡
Validate before you parse. A schema-valid message is much easier to reason about, and a parser that accepts junk will happily hand your business logic a decimal where the contract promised a time zone.

FAQ

Why does my decimal come back as 1.1000000000000001?
Somewhere in the pipeline it passed through a floating point type, often in a JavaScript client or an untyped mapping. Keep decimals decimal end to end.
Should I use xsd:date or xsd:dateTime for a timestamp?
dateTime, and always include the time zone offset. A bare local time is the leading cause of off-by-a-day calculation errors across regions.

WSDL contracts and code generation Interoperability between .NET, Java and legacy stacks

Last refreshed 2026-09-18.