1.1.1 Enumerated Values and Object Names

Editorial note: FTF  
Mike to provide text (Visa vs. Carte Bleu) [Owner: Mike]

Occiasionally, in the design of an application, there is a need to present enumerated values to an end-user to choose an option for completion of a transaction. Take, for example, an on-line purchase for travel. The credit cards, "Mastercard(r)" and "Visa(r)" have European counterparts known as "Eurocard(r)" and "Carte Bleu(r)" respectively. Each of these go through the same payment clearinghouses and are processed in the same way. It is common to see European payment sites stating that Matercard⁄Eurocard and Visa⁄CarteBleu are honored. However, outside of Europe, only the more common global brands are used.

In this example, a requester sends a user locale asks for valid payment methods to present to user. The locale would be the language of the user and the country in which the purchase is being made. The service then returns an enumerated list of accepted payment methods. The requester may have no previous knowledge of the payment methods, and so will rely on the service to provide the appropriate types to present to the user. The service will expect one of the values in the enumerated list to be returned as the payment type when completing the transaction.

From the Open Travel Alliance (OTA), we find the following valid enumeration values for credit cards:

(From http:⁄⁄www.opentravel.org⁄2004A⁄xsd⁄3⁄simpletype⁄PaymentCardCodeType.htm)

EnumerationDescription

Each of these would normally be presented in a pull-down pick list, but a particular organization may wish to discard with the differences, and present the list in Europe as:

...
VI  Visa⁄Carte Bleu
MC  Eurocard⁄Mastercard 
...

and in North America as:

 
... 
MC  Master Card 
VI  Visa 
...
1.1.1.1 Use of Default English-like Names

In an enumerated list, best practices dictate that there is an internal value from which actions are determined, and an external value, which is presented to an end user. In the same way, even if a service has been told what locale a requester is using, the service may want to provide alternate default display values, that can be used for debugging purposes or bilingual status or transaction displays.

1.1.1.2 Types of Names

Names in an enumerated list fall into three primary categories, each used for different purpose.

Display names are those which are presented to the user. A well designed system will have only the Requester generating and displaying these values. If necessary, a Requester should be able to request a set of standard localized names from a Service. Those names should be keyed to culture-neutral values that are used for communication between processes.

(from http:⁄⁄www.opentravel.org⁄2004A⁄xsd⁄9⁄complextype⁄SeatingPrefType.htm)

We'll choose a slightly different OTA example since credit card names are trademarked and don't change much from one language to another. Instead, we'll use seat selection for "Aisle", "Middle", "Center", "Window".

The OTA Schema, for instance, passes strings for this value, but an end-user will want to see the values in their own language. In German, the choices would be Gang, Mittleren, Mittel, and Fenster. Therefore, the designer of the Service may wish to return qualified locale sensitive display names that the Requester can use for display to the end user. This is especially useful for instances where terminology or messages might change and it is not desired to update the whole requester application just to update a few terms. 

<xs:attribute  name="SeatPosition"  type="xs:string"  use="optional">
    <xs:annotation>
        <xs:documentation  xml:lang="en">Preferred position of seat in a row, such as Aisle, Middle, Center, Window, etc.<⁄xs:documentation>
    <⁄xs:annotation>
    <xs:simpleType>
        <xs:restriction base="StringLength16">
            <xs:enumeration value="Aisle">
                <displayName xml:lang="en">Aisle<⁄display>
                <displayName xml:lang="de">Gang<⁄display>
            <⁄xs:enumeration>
            <xs:enumeration value="Middle">
                <displayName xml:lang="en">Middle<⁄display>
                <displayName xml:lang="de">Mittleren<⁄display>
            <⁄xs:enumeration>
            <xs:enumeration value="Center">
                <displayName xml:lang="en">Center<⁄display>
                <displayName xml:lang="de">Mittel<⁄display>
            <⁄xs:enumeration>
            <xs:enumeration value="Window">
                <displayName xml:lang="en">Window<⁄display>
                <displayName xml:lang="de">Fenster<⁄display>
            <⁄xs:enumeration>
        <⁄xs:restriction>
    <⁄xs:simpleType>
<⁄xs:attribute>

The actual enumeration value, not the displayName, would be used internally and passed from Requester to Service, while the displayName would be presented to the user interface according to locale.