Best Practice: Enumerating a set of items in XML Schema

Issue: You have a set of items that you wish to enumerate in your XML Schema. Should the items be enumerated using the enumeration facet or the pattern facet?

At the bottom of this message is an example of both approaches. The first uses the enumeration facet. The second uses the pattern facet.

Advantages of using the enumeration facet

1. With the enumeration facet each item can be annotated (using xs:annotation), whereas the pattern facet can only take a single annotation for the entire pattern.

2. With the pattern facet you must be careful of items containing regex-meaningful characters. For example, suppose your enumeration list has this item, A+B. The plus character has a special meaning in the regular expression language so you must break out of (escape) that meaning by preceding the plus with a backslash: A\+B. If the proper escaping is not done, it will result in an enumeration list containing unexpected items. For example, A+B denotes all of these items: AB, AAB, AAAB, … . With the enumeration facet you don’t have these concerns.

3. Suppose the enumeration list comes from another source. Then the enumeration facets can be directly populated from the source. If the pattern facet is used, the list might need to be preprocessed (e.g., escape regex-meaningful characters).

Advantages of using the pattern facet

1. Sometimes you must use the pattern facet. Consider this: the iCalendar RFC says that a calendar file contains these components – vevent, vtodo, vjournal, vfreebusy, valarm, vtimezone – plus extension components. Extension components have this form: x- followed by alphanumeric characters. In this case, the pattern facet must be used. Here’s how:

Acknowledgement

Thanks to the following people for their help in writing this best practice.

John Cowan
Eliot Kimber

Example of using the Enumeration Facet

<xs:element name="type">
    <xs:simpleType>
        <xs:restriction base="xs:string">
            <xs:enumeration value="contact" />
            <xs:enumeration value="acquaintance" />
            <xs:enumeration value="friend" />
            <xs:enumeration value="met" />
            <xs:enumeration value="co-worker" />
            <xs:enumeration value="colleague" />
            <xs:enumeration value="co-resident" />
            <xs:enumeration value="neighbor" />
            <xs:enumeration value="child" />
            <xs:enumeration value="parent" />
            <xs:enumeration value="sibling" />
            <xs:enumeration value="spouse" />
            <xs:enumeration value="kin" />
            <xs:enumeration value="muse" />
            <xs:enumeration value="crush" />
            <xs:enumeration value="date" />
            <xs:enumeration value="sweetheart" />
            <xs:enumeration value="me" />
            <xs:enumeration value="agent" />
            <xs:enumeration value="emergency" />
        </xs:restriction>
    </xs:simpleType>
</xs:element>

Example of using the Pattern Facet