Breadcrumbs

IXsdTypeConverter

Purpose

IXsdTypeConverter converts an XML Schema Definition (XSD) into runtime .NET types that can represent data described by the schema. The generated types include selected validation and documentation metadata derived from the XSD.

One possible use is to register a generated type as a runtime request-body type in an HTTP handler framework. This can help expose an XSD-described contract through an API.

Service contract 

IEnumerable<Type> Convert(Stream xsdStream, string typeNamespace);

The service reads and compiles the schema from the stream, then returns a CLR type for each global element. typeNamespace sets the .NET namespace used for generated types; it does not refer to the XSD target namespace.

The returned types are generated at runtime. Named XSD types referenced more than once are reused, and generated type names are adjusted when necessary to avoid collisions.

Supported mappings

Elements and complex types

  • Global elements are converted into returned CLR types.

  • Complex types whose content is an xs:sequence or xs:all become CLR types with properties for their child elements.

  • Nested complex elements become nested generated CLR types.

  • An empty complex type becomes a type with no properties.

  • Element documentation becomes description metadata on the corresponding property. Documentation on a global element becomes description metadata on its generated root type.

  • XML attributes are ignored; they do not become CLR properties.

Occurrence constraints

  • An element with maxOccurs greater than 1 becomes an IEnumerable<T> property.

  • For a non-repeating element, minOccurs > 0 marks the property as required.

  • For a repeating element, the property is marked as required and given a minimum collection length based on minOccurs.

Built-in simple types

XSD types

CLR type

string, dateTime, duration, hexBinary, base64Binary, anyURI, date, time, gYearMonth, gYear, gMonthDay, gDay, gMonth, normalizedString, token, language, ID, IDREF, ENTITY, NOTATION, IDREFS, ENTITIES, NMTOKEN, NMTOKENS, Name, QName, NCName

string

boolean

bool

float

float

double

double

decimal

decimal

integer, nonNegativeInteger, positiveInteger, nonPositiveInteger, negativeInteger, int, long, unsignedLong

long

short

short

byte, unsignedByte, unsignedInt, unsignedShort

string

For user-defined simple types, the converter follows the base type to determine the CLR type. If it cannot resolve the type, it falls back to string.

Restrictions and validation

Enumerations: A simple type restriction containing enumeration values becomes a CLR enum.

Patterns: Pattern restrictions are carried into validation using XSD pattern semantics, rather than treating the values as .NET regular expressions. Multiple patterns at the same restriction level are alternatives; restrictions inherited from different levels must all be satisfied. Applicable whitespace rules are also taken into account. For repeating values, each item is checked.

Date and time: Elements that ultimately resolve to xs:dateTime are represented as string values and checked for the XSD date-time lexical shape: a date and time separated by T, with optional fractional seconds and an optional timezone. Values are also checked for date-time parseability. Empty or null values pass this format check; requiredness is handled separately by the element’s occurrence constraint. Repeating date-time values are checked individually.

These mappings are not complete XSD validation. For example, length and numeric range facets are not generally projected into generated validation. Consumers should treat the generated validation as the subset implemented by the converter, not as a guarantee that every XSD constraint is enforced.

Unsupported or ignored features

  • xs:choice is not supported and causes conversion to fail.

  • An element without a type, or declared as xs:anyType, is not supported and causes conversion to fail.

  • XML attributes are ignored, including attributes on complex types and simple-content types.

  • xs:any particles are ignored.

  • The converter handles sequence and all particles; other particle forms it cannot process can cause conversion to fail.

Potential use with HTTP handlers

A consumer can use IXsdTypeConverter to generate a CLR type from a schema, then register that type as a runtime request-body type with an HTTP handler framework. The framework can use the generated type and its validation metadata when processing requests. Endpoint routing and request processing remain responsibilities of the consuming application.

A schema can produce multiple types if it contains multiple global elements. Consumers that need one request type per endpoint should ensure the schema resolves to exactly one global element type.