W3C

Web Services Internationalization Usage Scenarios

W3C Working Draft 20 December 2002

This version:
http://www.w3.org/TR/2002/WD-ws-i18n-scenarios-20021220
Latest version:
http://www.w3.org/TR/ws-i18n-scenarios
Previous version:
none
Editors:
Kentaroh Noji, IBM <nojik@jp.ibm.com>
Martin J. Dürst, W3C <duerst@w3.org>
Addison Phillips, webMethods
Takao Suzuki, Microsoft
Tex Texin, XenCraft

This document is also available in these non-normative formats: XML.


Abstract

This document describes a variety of Web Services internationalization usage scenarios and use cases.

Some of the usage scenarios and use cases of this document may be used to generate internationalization requirements for Web Services technologies, and best practices for the internationalization of Web Services.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this series of documents is maintained at the W3C.

This is the first working draft of a document which describes Web Services internationalization usage scenarios for review by W3C members and other interested parties. It has been produced by the Web Services Internationalization Task Force of the W3C Internationalization Working Group, as part of the W3C Internationalization Activity.

Discussion of this document takes place on the public mailing list public-i18n-ws@w3.org. To follow and contribute, please subscribe by sending mail to public-i18n-ws-request@w3.org with subscribe as the subject. The archive of this list can be read by the general public.

We invite contributions of additional Usage Scenarios and Use Cases to document aspects of Web Services internationalization that are not covered yet in this document. To contribute, please use a format similar to the one used in this document, and send your contribution to the www-i18n-comments@w3.org mailing list (public archive). Please use [Web Services] or [WSUS] in the subject.

At the time of publication, the Working Group believed there were no patent disclosures relevant to this specification. A current list of patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page.

This document is work in progress and does not imply endorsement by, or the consensus of, either W3C, or members of the Web Services Task Force of the W3C Internationalization Working Group. This document still contains incomplete descriptions in various places.

This document is a draft version, and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". A list of all technical reports can be found at http://www.w3.org/TR/.

Table of Contents

1 Introduction
    1.1 Scope
2 Usage Scenarios
    2.1 Data Integrity and Interoperability
        2.1.1 Data Integrity in Unicode Encoding
            2.1.1.1 Scenario Definition
            2.1.1.2 Description
        2.1.2 Data Integrity in Non-Unicode Encoding
            2.1.2.1 Scenario Definition
            2.1.2.2 Description
    2.2 Language(Locale) Negotiation for SOAP Fault Messages
        2.2.1 Natural Languages for SOAP Fault Messages
            2.2.1.1 Scenario Definition
            2.2.1.2 Description
        2.2.2 Fault Reason Messages in All Available Languages
            2.2.2.1 Scenario Definition
            2.2.2.2 Description
        2.2.3 Language Selection for Fault Reason Messages
            2.2.3.1 Scenario Definition
            2.2.3.2 Description
        2.2.4 Default Language for SOAP Fault Messages
            2.2.4.1 Scenario Definition
            2.2.4.2 Description
        2.2.5 Language Preference for Chained Services
            2.2.5.1 Scenario Definition
            2.2.5.2 Description
        2.2.6 Locale Sensitive Formated Data in SOAP Fault Messages
            2.2.6.1 Scenario Definition
            2.2.6.2 Description
        2.2.7 Language Preference for "One Way Message"
            2.2.7.1 Scenario Definition
            2.2.7.2 Description
        2.2.8 Language Preference for Multiple Transmission Protocols Binding
            2.2.8.1 Scenario Definition
            2.2.8.2 Description
        2.2.9 HeaderFault vs. Fault
            2.2.9.1 Scenario Definition
            2.2.9.2 Description
        2.2.10 Caching Affects Results
            2.2.10.1 Scenario Definition
            2.2.10.2 Description
        2.2.11 Locale Affected Fault Evaluation
            2.2.11.1 Scenario Definition
            2.2.11.2 Description
        2.2.12 Request-Response vs. Connection-less
            2.2.12.1 Scenario Definition
            2.2.12.2 Description
        2.2.13 Peer-to-Peer Fault
            2.2.13.1 Scenario Definition
            2.2.13.2 Description
    2.3 Locale Neutral vs. Sensitive Data Exchanging
        2.3.1 Locale Neutral Formated Data
            2.3.1.1 Scenario Definition
            2.3.1.2 Description
        2.3.2 Data with Additional 'Attributes'
            2.3.2.1 Scenario Definition
            2.3.2.2 Description
        2.3.3 Data with Default 'Attribute'
            2.3.3.1 Scenario Definition
            2.3.3.2 Description
        2.3.4 Locale Dependent Datatypes
            2.3.4.1 Scenario Definition
            2.3.4.2 Description
        2.3.5 Correlation of Data among Services in Different Languages
            2.3.5.1 Scenario Definition
            2.3.5.2 Description
    2.4 Locale Sensitive Presentation
        2.4.1 Data Formatting for End User on Receiver Side
            2.4.1.1 Scenario Definition
            2.4.1.2 Description
        2.4.2 Data Formatting on Sender Side
            2.4.2.1 Scenario Definition
            2.4.2.2 Description
        2.4.3 Data Formatting on Receiver Side according to Sender
            2.4.3.1 Scenario Definition
            2.4.3.2 Description
    2.5 Locale Sensitive Data Processing
        2.5.1 Locale Sensitive Processing by Provider(Receiver)
            2.5.1.1 Scenario Definition
            2.5.1.2 Description
                2.5.1.2.1 Transport Layer (HTTP, SMTP/MIME, etc.)
                2.5.1.2.2 Service Provider Layer
                2.5.1.2.3 Service Layer
        2.5.2 Opaque Identifier to Identify a Locale
            2.5.2.1 Scenario Definition
            2.5.2.2 Description
    2.6 Finding Services
        2.6.1 Searching for Web Services
            2.6.1.1 Scenario Definition
            2.6.1.2 Description
        2.6.2 Fall-Back for Internationalized Web Services
            2.6.2.1 Scenario Definition
            2.6.2.2 Description
    2.7 Services for Internationalization Functionality
        2.7.1 Outsourcing Locale-Related Services
            2.7.1.1 Scenario Definition
            2.7.1.2 Description
        2.7.2 Propagating Updates related to Locales
            2.7.2.1 Scenario Definition
            2.7.2.2 Description
    2.8 Development of Internationalized Web Services
        2.8.1 Internationalizing an Existing Web Service
            2.8.1.1 Scenario Definition
            2.8.1.2 Description
        2.8.2 Communicating Available Options
            2.8.2.1 Scenario Definition
            2.8.2.2 Description
    2.9 Template
        2.9.1 Title
            2.9.1.1 Scenario Definition
            2.9.1.2 Description
3 Use Case

Appendices

A References (Non-Normative)
B Acknowledgements (Non-Normative)
C Heisei (Non-Normative)


1 Introduction

This document describes a variety of Web Services internationalization usage scenarios and use cases.

The goal of the Web Services Internationalization Task Force is to ensure that Web Services have robust support for global use, including all of the world's languages and cultures.

The goal of this document is to examine the different ways that language, culture, and related issues interact with Web Services architecture and technology. Ultimately this will allow us to develop standards and best practices for those interested in implementing internationalized Web Services. We may also discover latent international considerations in the various Web Services standards and propose solutions to the responsible groups working in these areas.

Web Services provide a world-wide distributed environment that uses XML based messaging for access to distributed objects, application integration, data/information exchange, presentation aggregation, and other rich machine-to-machine interaction. The global reach of the Internet requires support for the international creation, publication and discovery of Web Services. Although the technologies and protocols used in Web Services (such as HTTP [RFC2616], XML [XML], XML Schema, and so forth) are generally quite mature as "international-ready" technologies, Web Services may require additional perspective in order to provide the best internationalized performance, because they represent a way of accessing distributed logic via a URI.

As a result, this document attempts to describe the different scenarios in which international use of Web Services may require care on the part of the implementer or user or to demonstrate potential issues with Web Services technology.

This document describes the followings scenarios:

  1. Locale neutral vs. locale-sensitive XML messages and data exchange

  2. Interaction between Web services and the underlying software system's international functionality

  3. Message processing in Web Services, e.g. SOAP Fault messages etc.

The scope of this document is described in Section 1.1 below.

1.1 Scope

This document follows the definition of Web Services specified in Chapter 2 of the Web Services Architecture document [WSA].

Definition: A Web service is a software system identified by a URI, whose public interfaces and bindings are defined and described using XML. Its definition can be discovered by other software systems. These systems may then interact with the Web service in a manner prescribed by its definition, using XML based messages conveyed by Internet protocols.

In order to narrow down the scope, the usage scenarios in this document are limited to the following W3C technologies and deliverables:

Internationalized Web Services need to be easy to create, publish and discover for a wide range of audiences.

The scope of Web Services internationalization is W3C internationalization working group deliverables, including:

  • Web services requirements

  • Unicode technologies and deliverables

  • Concepts and application of distributed locales and locale-affected preferences

  • Web services internationalization best practices

2 Usage Scenarios

2.1 Data Integrity and Interoperability

2.1.1 Data Integrity in Unicode Encoding

2.1.1.1 Scenario Definition

A sender and a receiver wish to use Unicode encoding to transmit data between each other. This scenario provides an example of best practice.

2.1.1.2 Description

SOAP is used for XML messages exchanging data among service nodes. Because all XML [XML] processors must be able to read entities in both the UTF-8 [RFC2279] and UTF-16 [RFC2781] encodings, using UTF-8 or UTF-16 guarantees character encoding interoperability on the SOAP layer. The Character Model for the World Wide Web [CHARMOD] document describes these considerations and guidelines.

Note: WS-I: Web Services Interoperability basic profile [WSI-BP] document describes a problem about Unicode encoding and Byte Order Mark (BOM) handling.

Applies to: SOAP, SOAP interface of software systems

2.1.2 Data Integrity in Non-Unicode Encoding

2.1.2.1 Scenario Definition

A sender and receiver wishes to use non-Unicode encoding. This scenario provides an example of best practice.

2.1.2.2 Description

This scenario is divided into three aspects.

  1. A sender sends a SOAP message in non-Unicode encoding.

  2. A receiver receives a SOAP message in non-Unicode encoding.

  3. Interaction between SOAP layer and SOAP interface such as programming language, middleware, operating systems etc.

When a sender sends a SOAP messages in a non-Unicode encoding to a receiver, the receiver may not accept the non-Unicode encoding. The sender does not always accept all character encodings that may be used with XML. In order to use a non-Unicode encoding in a SOAP message, the sender needs to know beforehand whether the receiver is able to accept the non-Unicode encoding.

Receiver passed SOAP messages to programming languages, middleware, or operating systems via SOAP interface. Through the interaction of SOAP interface, code conversion from non-Unicode encoding to Unicode may happen.

XML Japanese profile document [XML-JP] describes that using non-Unicode encodings such as Shift_JIS cannot provide interoperability in information interchange.

Applies to: SOAP, SOAP interface of software systems

2.2 Language(Locale) Negotiation for SOAP Fault Messages

2.2.1 Natural Languages for SOAP Fault Messages

2.2.1.1 Scenario Definition

In SOAP RPC scenario, a requester wishes to tell the requester's language preference to the provider in order to receive SOAP fault messages in the requester's preferred language.

2.2.1.2 Description

When a SOAP fault occurs, SOAP fault messages containing natural language descriptions of the error(s) are sent back to the requester. The requester usually wants to see error messages in the requester's preferred language(s) and data format. Currently the following mechanism is available with the HTTP binding.

Accept-language: The Accept-Language request-header field restricts the set of natural languages that are preferred as a response to the request. [RFC2616]

Using Accept-language, a requester can notify a provider of the requester's language preference. A provider can then send SOAP-Fault messages in the requester's preferred language(s). If a SOAP message does not use the HTTP binding, how can a SOAP-Fault message detect the requester's language preference.

SOAP fault messages sent back contain text in natural language(s). SOAP fault messages should include xml:lang so that a requester can process SOAP fault messages based on the xml:lang identification.

Applies to: SOAP, or an extension of SOAP

2.2.2 Fault Reason Messages in All Available Languages

2.2.2.1 Scenario Definition

Service provider needs to return fault messages in all available languages.

2.2.2.2 Description

The Service Requester sends a SOAP document containing an error to the Service Provider. The provider generates a response containing a SOAP fault. In order to provide for multi-lingual response under the current design, the provider must return all available languages. The provider cannot know what languages (resources) are installed. Most programming environments do not provide functionality that enumerates which languages are actually installed, so the service provider must request every possible installed locale in turn in order to poll whether the string is available in that language. Since resources are often sparsely populated, this suggests significant processing overhead to loop over all possible locales, loading resources in turn.

Applies to: SOAP, or an extension of SOAP

2.2.3 Language Selection for Fault Reason Messages

2.2.3.1 Scenario Definition

Service requester must select a matching language from the list of fault reasons returned by the service provider.

2.2.3.2 Description

The requester may be unable to (validly) match the returned text values to its current (end user) language.

Example: SOAP fault reason messages in multiple languages
<env:faultReason>
 <env:Text xml:lang="en-US">Processing error</env:Text>
 <env:text xml:lang="cs">Chyba zpracování</env:Text>
</env:faultReason>

If the requester is in locale "en-GB", then neither string will be considered a match for the current requester language preference. Although it is apparent to a human that en-US is a reasonable match for en-GB, automated processes are not permitted to make this assumption. ("en" would be a match for both "en-US" and "en-GB").

Applies to: SOAP, or an extension of SOAP

2.2.4 Default Language for SOAP Fault Messages

2.2.4.1 Scenario Definition

The service provider must return fault messages in all available languages, since it doesn't know the language of the requester.

2.2.4.2 Description

Many operating environments are localized into a large number of languages (for example, Microsoft supports 33 languages in 120+ locales or regional variations). SOAP Fault reason messages might become substantial in size if every language must be returned.

Applies to: SOAP, or an extension of SOAP

2.2.5 Language Preference for Chained Services

2.2.5.1 Scenario Definition

The service defines a language preference in SOAP Header. The service is then chained.

Editorial note: KN2002-12-10
The latest SOAP V1.2 Part 1 Specification (Editor's draft) mentions language preference.
2.2.5.2 Description

Service "A" defines a header containing a language request field. This service is deployed.

Service "B" defines a service that includes a call to Service "A", but defines no header.

Requester calls service "B" with arguments that cause Service "A" to generate a fault. Because there is no standardized header format, Service "A" cannot generate the faultReason in the language of the requester.

Applies to: SOAP, or an extension of SOAP

2.2.6 Locale Sensitive Formated Data in SOAP Fault Messages

2.2.6.1 Scenario Definition

FaultReason must substitute locale-sensitive data into text message.

2.2.6.2 Description

Service "A" is defined on Provider "A". A fault is generated during invocation that returns a faultReason that includes locale affected values.

  • "The date provided, 12 November 2201, was too late."

  • "The argument 12345.678 was too large."

  • "The argument 12345,678- was too small."

How does the provider perform the substitutions?

Applies to: SOAP, or an extension of SOAP

2.2.7 Language Preference for "One Way Message"

2.2.7.1 Scenario Definition

Service Oriented Architecture Derivative Patterns One Way Message

2.2.7.2 Description
  1. Service "A" is defined to receive a message from Requester "A" and deliver to Requester "B" via Service "B". An example of this would be similar to a mail server triggered by a Web service.

  2. Requester "A" calls Service "A".

  3. Service "B" is unable to complete its message transaction and generates a fault.

  • What language does "B" return?

  • Does Provider "A"'s locale influence the language returned?

Applies to: SOAP, or an extension of SOAP

2.2.8 Language Preference for Multiple Transmission Protocols Binding

2.2.8.1 Scenario Definition

SOAP message variation if http or ftp or SMTP or RMI or IIOP (difficulty deploying in a single WSDL)

2.2.8.2 Description
  1. Service "A" is defined on Provider "A".

  2. The administrator of Provider "A" wishes to deploy the same service on several bindings simultaneously in the same WSDL file.

  • SOAP structure requires different semantics for language preference for each binding?

2.2.9 HeaderFault vs. Fault

2.2.9.1 Scenario Definition

HeaderFault vs.Fault

2.2.9.2 Description
  1. Service "A" is defined on Provider "A" and invoked by Requester "A".

  2. Service generates a fault from the header. Provider "A" returns the faultReason.

  3. Later Requester "A" invokes again. This time the actual service generates a fault (and presumably the faultReason).

Can a fault generated by the actual service return multiple language versions of itself? Or would the service actually generate faults only in the language that the service is running in (the environment or context of the server). If there were a "userLocale" or "userLanguage" defined in the service provider this wouldn't necessarily be an issue.

2.2.10 Caching Affects Results

2.2.10.1 Scenario Definition

Caching affects results.

2.2.10.2 Description
  1. Caching is not well described in SOAP and Web Services architecture just yet.

  2. If caching is permitted and is separate from service execution and there is no standardized language negotiation mechanism, it is possible that cached responses in the wrong language could be returned.

2.2.11 Locale Affected Fault Evaluation

2.2.11.1 Scenario Definition

Locale affected fault evaluation.

2.2.11.2 Description
  1. Service "A" is defined on Provider "A", running in an English locale. The service requires that the value of string variable "foo" be less than "zzz".

  2. Requester "A" is running in a French locale and sends a SOAP request with foo="écrit".

  3. Provider "A" returns a fault, even though in French the string is "less than" the evaluated value.

2.2.12 Request-Response vs. Connection-less

2.2.12.1 Scenario Definition

Request-response versus connection-less.

2.2.12.2 Description
Editorial note: AF2002-11-27
Needs more work.

2.2.13 Peer-to-Peer Fault

2.2.13.1 Scenario Definition

Peer-to-Peer faults.

2.2.13.2 Description
  1. Service "A" and Service "B" are defined as "peer-to-peer" services (that is, each service may invoke the other service or be invoked by the other service).

  2. Service "A" invokes Service "B", generating a fault.

Editorial note: KN2002-12-15
Needs to describe what internationalization is.

2.3 Locale Neutral vs. Sensitive Data Exchanging

2.3.1 Locale Neutral Formated Data

2.3.1.1 Scenario Definition

A sender wishes to send data to a receiver. The sender does not know the kind of formatting conventions that the receiver is using for various types of data. This usage scenario does not raise any requirements. It provides an example of best practice.

2.3.1.2 Description

If the sender does not know the kind of formatting conventions that the receiver is using for a particular type of data, the sender has to use well-known, locale-neutral formatting conventions. XML Schema (Part 2, Datatypes)[XMLS-2] provides such such formatting conventions. Although SOAP can support various XML encodings, SOAP specifies the common data types such as SOAP encoding which is for general cases: e.g. RPC scenario for basic interoperability. SOAP encoding is based on XML Schema.

The following data types are related to date and time. They are built-in primitive types which are specified in XML Schema Part 2.

Example: Locale neutral formated data in XML Schema
   TYPE            : EXAMPLE               
   ---------------- ---------------------------
   date            : 2003-05-31
   time            : 13:20:00
   tz              : +09:00
   dateTime        : 2003-05-31T13:20:00+09:00
   
   double          : 1267.43233E12
   decimal:integer : 2678967543233

The above data types keep interoperability from a lexical analysis perspective. When a SOAP sender sends e.g. a date to a SOAP receiver using the above date type, both sender and receiver can interpret the date lexically.

Editorial note: F2F2002-11-23
Distinction of locale-neutral formatting and culture-neutral semantics.

On the other hand, date is accompanied with location. For example, 2003-05-31 in Korea is not exactly the same period of time as 2002-05-31 in France, but it is the same as 2003-05-31 in Japan. Date varies by time-zone which is related to regional government and geography etc. In processing SOAP encoding or XML Schema data types, it is necessary to distinguish locale-neutral data formatting and locale-neutral data semantics. Using SOAP encoding or XML Schema ensure locale-neutral data format, but does not ensure locale-neutral data semantics.

The following example is a SOAP message in SOAP encoding. Although all of the following data are locale-neutral formatting, the context of data differs from one location/culture to another.

Example: Locale neutral formated data
   <?xml version='1.0' ?>
   <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
    <env:Header>
    </env:Header>
   <env:Body>
    <c:getAvailableFlightResponse xmlns:c="http://trip.example/query">
     <c:price>123.55</c:price>
     <c:departuredate>2003-05-31</c:departuredate>
     <c:departuretime>13:30:00</c:departuretime>
    </c:getAvailableFlightResponse>
   </env:Body>
   </env:Envelope>

SOAP transactions can use SOAP encoding/XML Schema to assure that there is no ambiguity in transactions between senders and receivers in order to keep lexical analysis interoperability. Additional attributes may be needed to assure the data semantics. Detailed scenarios are described in the next section.

Applies to: Web Services in general

2.3.2 Data with Additional 'Attributes'

2.3.2.1 Scenario Definition

A sender wishes to send monetary data to a receiver. Each of the monetary amounts has a specific currency. This usage scenario does not raise any requirements. It provides an example of best practice.

2.3.2.2 Description

SOAP messages are sent to a receiver using XML schema data types such as integer, double, float, date, time etc. However, these data types may have locale sensitive semantics such as currency and location. In order to add data semantics, adding attributes is frequently used for XML messaging scenario.

Example: Locale neutral formated data with additional attributes
   <?xml version='1.0' ?>
   <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
    <env:Header>
    </env:Header>
    <env:Body>
     <c:getAvailableFlightResponse>
      <c:price c:currency="USD">123.55</c:price>
      <c:departuredate c:location="JFK">2003-05-31</c:departuredate>
      <c:departuretime c:location="JFK">13:30:00</c:departuretime>
     </c:getAvailableFlightResponse>
    </env:Body>
   </env:Envelope>

Another option is to use a structure consisting of two elements for RPC scenario using SOAP encoding.

Example: Locale neutral formated data with additional semantic data
   <?xml version='1.0' ?>
   <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
    <env:Header>
    </env:Header>
    <env:Body>
     <c:getAvailableFlightResponse>
      <c:price>
       <c:currency>USD<c:currency>
       <c:amount>123.55</c:amount>
      </c:price>
      <c:departuredate>
       <c:location>JFK</c:location>
       <c:date>2003-05-31</c:date>
      </departuredate>
      <c:departuretime>
       <c:location>JFK</c:location>
       <c:date>2003-05-31</c:date>
      </departuretime>
     </c:getAvailableFlightResponse>
    </env:Body>
   </env:Envelope>

Applies to: Web Services in general

2.3.3 Data with Default 'Attribute'

2.3.3.1 Scenario Definition

A sender wishes to send monetary data to a receiver. Sender and provider may use arbitrary currencies, but both sender and receiver do not use multiple currencies. They wish to set a default currency for one SOAP message.

Editorial note: F2F2002-11-23
This seems to be a use case related to integration of legacy systems, not a clean design. This should be explained clearly, or the use case should be removed.
2.3.3.2 Description

Additional attribute is frequently used for monetary data exchange as mentioned above section. The following example shows multiple currency data transmission in a SOAP message.

Example: Multiple currencies in SOAP message
   <?xml version='1.0' ?>
   <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope" >
    <env:Header>
    </env:Header>
    <env:Body>
     <c:purchase>
      <c:apple>
       <c:currency>JPY</c:currency>
       <c:amount>123.55</c:amount>
      </c:apple>
      <c:orange>
       <c:currency>USD</c:currency>
       <c:amount>325.78</c:amount>
      </c:orange>
     <c:peach>
      <c:currency>EUR</c:currency>
      <c:amount>36.55</c:amount>
     </c:peach>
    </c:purchase>
   <env:Body>
   </env:Envelope>

Most regional services use a default currency instead of multiple currencies. For example, Japanese internal shopping uses JPY by default. The following is an example which has the default currency in SOAP header. It is possible to specify the default currency attribute in SOAP body instead of SOAP header.

Editorial note: KN2002-12-10
Namespace:WS-I18N is an example. It is neither specification nor standard.
Example: Default attribute in SOAP header
   <?xml version='1.0' ?>
   <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope" >
    <env:Header>
     <WS-I18N:WSinternationalization xmlns:WS-I18N="http://example.org/2002/11/21/WS-I18N">
      <WS-I18N:Currency>JPY</WS-I18N:Currency>
     </WS-I18N:WSinternationalization>
    </env:Header>
   <env:Body>
    <c:purchase>
     <c:apple>
      <c:price>123.55</c:price>
     </c:apple>
     <c:orange>
      <c:price>325.78</c:price>
     </c:orange>
     <c:peach>
      <c:price>36.55</c:price>
     </c:peach>
     </c:purchase>
    </env:Body>
   </env:Envelope>

Although adding parameter to SOAP body requires design change for service interface, adding default value into SOAP header does not affect services interface.

Applies to: Web Services General

2.3.4 Locale Dependent Datatypes

2.3.4.1 Scenario Definition

A sender wishes to send locale dependent data to a receiver for regional SOAP messaging or RPC. The receiver needs to process the locale dependent data correctly.

2.3.4.2 Description

If a Japanese sender sends date data to a Japanese receiver, the Japanese sender wishes to send data in Japanese calendar's date such as H13-5-31(H means Heisei era; see Appendix C Heisei) to the receiver.

Example: Locale sensitive data in regional datatype
   <?xml version='1.0' ?>
   <env:Header>
    <WS-I18N:WSinternationalization
       xmlns:WS-I18N="http://example.org/2002/11/21/WS-I18N">
     <WS-I18N:dataTypePreference>
      <ja:JDate xmlns:ja="http//example.org/2003/12/3/ja">EYY-MM-DD</WS-I18N:JDate>
     </WS-I18N:dataTypePreference>
    </WS-I18N:WSinternationalization>
   </env:Header>
   <env:Body>
    <departuredate>H14-5-31</departuredate>
   </env:Body>

Default is Locale neutral mode. If a sender and a receiver can handshake with each other using the same semantics of locale, sender can send a locale dependent data to a receiver, and the receiver can process the data consistently.

If WSDL can describe locale sensitive datatypes, locale negotiation mechanism can be described in WSDL. Is it applicable requirement for interface definition of WSDL?

Editorial note: KN2002-12-10
Possible datatype: Telephone number, ZIP code etc. Needs feasibility assessment.

There is a difference between data types such as telephone number, ZIP code, etc., which can be modeled as strings with patterns, and data types such as dates and numbers, where a connection with the value space (e.g. of XML Schema) may be desirable.

Applies to: WSDL, SOAP, or Localizable datatype

2.3.5 Correlation of Data among Services in Different Languages

2.3.5.1 Scenario Definition

A service is defined using "Service Oriented Architecture Derivative Patterns Intermediary" as found in Web Services Architecture document[WSA].

2.3.5.2 Description
  1. Service "A" is defined as a service that returns status text and deployed on Providers "A1", "A2", and "A3" in different language configurations (locales).

  2. Provider "B" polls Service "A" on each machine and caches the results.

  3. Service "B" is defined as a process that returns cached results and is deployed on Provider "B".

  4. Requesters "C1", "C2", and "C3", each with different language preferences, invoke Service "B" sporadically to obtain data.

  • Provider "B" must cache faults and data in all possible languages since it cannot know in advance which requesters will want what data.

  • Provider "B" must send all data to each requester.

  • Correlation of data may prove difficult.

2.4 Locale Sensitive Presentation

2.4.1 Data Formatting for End User on Receiver Side

2.4.1.1 Scenario Definition

Data is formatted for an end user by the receiver according to the end user's preferences and the system conventions. This usage scenario does not raise any requirements. It provides an example of best practice.

2.4.1.2 Description

The receiver may format data in order to display the data in a user interface. Locale sensitive data formatting functions are widely provided by internationalization functionality of operating systems, programming languages, or applications such as word processors and middleware. Therefore, an application can format locale neutral data using built-in internationalization functions. The details of data formatting vary across different systems. Therefore, Web services themselves do not guarantee completely identical formatting on different systems.

Applies to: Web Services General

2.4.2 Data Formatting on Sender Side

2.4.2.1 Scenario Definition

The sender formats data for viewing by an end user on the receiver side. The sender takes care of data formatting to assure consistency of presentation.

2.4.2.2 Description
Editorial note: F2F2002-11-23
Explain in more detail why the consistency is needed/desirable. Give examples. Ways this could be done: Producing HTML (+styles). Other reasons may be that the recipient asked for specific formatting.

2.4.3 Data Formatting on Receiver Side according to Sender

2.4.3.1 Scenario Definition

A receiver formats data according to the format provided by the sender.

2.4.3.2 Description

Data sent by a sender is formatted by the receiver according to format(s) provided by the sender. This is different from scenario 2.13 and 2.14 in that the center of decision and the actual execution of the formatting are separated. Scenario 2.13 or 2.14 should be preferred because they are more straightforward, but this scenario may be chosen for various reasons such as: The sender wants to ensure consistent appearance, and the data may be used on the receiver side both for formatting and for further processing.

Editorial note: F2F2002-11-23
We need more details and better arguments for why the server wants consistency, and maybe examples of what degree of consistency is necessary/desirable in different applications.

Data formatting rules should be sent to receivers together with data, in order to keep consistency self-descriptively, for user interface.

Editorial note: F2F2002-11-23
There may be other ways to tell the receiver what exactly to do, e.g. by referencing rather that including formatting rules.

The following is a pair of float data and an example of numeric formatting rule.

    Value: float: 235055.55
    Numeric formatting rule: #.##.##0,##

Presentation result for user interface is:

    2.35.055,55

The following example shows a way to send a formatting rule in SOAP header together with a float value.

Example: Locale neutral formated data with formatting rule
    <?xml version='1.0' ?>
    <env:Header>
     <WS-I18N:WSinternationalization
       xmlns:WS-I18N="http://example.org/2002/11/21/WS-I18N">
      <WS-I18N:presentationPreferences>
       <WS-I18N:NumericFormat>#.##.##0,##</WS-I18N:NumericFormat>
       </WS-I18N:presentationPreferences>
     </WS-I18N:WSinternationalization>
    </env:Header>
    <env:Body>
     <value>235055.55</value>
    </env:Body>

Because a receiver receives a value in locale neutral decimal data together with formatting rule, the receiver can format the data for user interface self-descriptively.

Applies to: Web Services General

2.5 Locale Sensitive Data Processing

2.5.1 Locale Sensitive Processing by Provider(Receiver)

2.5.1.1 Scenario Definition

The service provider needs the locale of the sender in order to perform locale sensitive processing. There are three levels to this: Transport layer, service provider layer (SOAP Header), and service layer (SOAP Body) (we need separate scenarios for these)

2.5.1.2 Description
2.5.1.2.1 Transport Layer (HTTP, SMTP/MIME, etc.)

Note that this layer includes more than just Web services. It also includes XHTML [XHTML], XForms [XFORMS], and other locale-sensitive applications on the Web. The service provider receiving the document needs to know the sender's locale preferences in order to perform locale-sensitive processing. This may include routing based on language or regional preferences, selection of response language, formatting of error messages (if the SOAP document is unintelligible/non-parse-able, what language is the failure message returned in?).

2.5.1.2.2 Service Provider Layer

As shown elsewhere, locale-sensitive processing requires a locale to be passed to the Web service somehow. Most Web services, however, are not explicitly locale-sensitive operations. They may still need a locale in their context (for obtaining resources, obtaining the preferred collation, etc.). The Web service author should not have to specify a Locale in the actual service definition, since it has no bearing on the actual data structures involved in the process. For example: xlxlx The Service Provider (SOAP container) also must process the actual SOAP message and generate SOAP fault messages. These may be locale- or language-affected.

2.5.1.2.3 Service Layer

Each Web service may need to have a specific locale applied to a specific piece of data (in a data structure) or as an argument passed in. Exposing the specific locale structure of the back-end system removed platform independence.

Applies to: Web Services General

2.5.2 Opaque Identifier to Identify a Locale

2.5.2.1 Scenario Definition

Using an opaque identifier to identify a locale.

2.5.2.2 Description

Same locale processing does not always return same result, because there are locale implementation differences among runtime environment.

A sender(requester) wishes a provider(receiver) to return a result of specific locale sensitive processing such as Java Locale, Windows Locale, or POSIX locale etc

Because user can customize locale, a sender(requester) wishes a provider(receiver) to return a result of locale sensitive processing based on the sender customized locale.

Applies to: A locale identification which distinguishes runtime differences or users customization.

2.6 Finding Services

2.6.1 Searching for Web Services

2.6.1.1 Scenario Definition

Searching for Web services depending on language or culture.

2.6.1.2 Description

Repositories and search-able meta-data (such as UDDI [UDDI]) about Web services need to provide support for multiple language searches. Transport layer issues do not allow XML data structures to be used for resolution, except by reference (e.g. the receiver must down-load a separate resource asynchronously to "decode" the preference). Tags on this layer may be necessary in place of XML data structures.

Editorial note: KN2002/12/13
UDDI provides TAXONOMY based on the ISO 3166 Geographic Code System.

2.6.2 Fall-Back for Internationalized Web Services

2.6.2.1 Scenario Definition

There is no way for the service to find the best appropriate match when the user's request cannot be met.

2.6.2.2 Description

If the sender specified "ja-JP" and "ja-JP" is not available at the receiver, what should the fall-back schema be?

Editorial note: F2F2002-11-23
Need to more clearly define this scenario and provide examples.

2.7 Services for Internationalization Functionality

2.7.1 Outsourcing Locale-Related Services

2.7.1.1 Scenario Definition

Using a Web service to obtain some locale-related service, such as formatting, collation etc.

2.7.1.2 Description

Some locale-related tasks are not easy to describe by an exchangeable data structure. Also, not all systems will have code for all locales. It may therefore be desirable in some cases to 'outsource' locale services.

Example 1: Formatting a date according to traditional Thai conventions (the full text of the formatted date is very long)

Editorial note: F2F2002-11-23
Add example.

Example 2: Converting a date according to local rules that may not be predictable.

Example 3: Collation data can be very large, and collation may include additional domain-specific preprocessing in addition to the simple comparison of strings. It may therefore in some cases be more efficient to send the data to be sorted to another system.

2.7.2 Propagating Updates related to Locales

2.7.2.1 Scenario Definition

Using Web services to update locale-related data that may change dynamically and/or in ways that are not easily predictable.

2.7.2.2 Description

Some kinds of data needed for culturally sensitive operations is not easily predictable. Web services may be used to update such data, either by polling for updates or by sending out updates.

Example: Certain calendars depend on actually observed events, such as the actual observation of the new moon.

Editorial note: F2F2002-11-23
Add more specific details here.

Example: Jurisdictions once in a while may change their rules for which time-zones they are in at which time of the year.

Issues: Scalability; requests may concentrate at specific times; polling may have to be repeated over and over without any actual updates.

2.8 Development of Internationalized Web Services

2.8.1 Internationalizing an Existing Web Service

2.8.1.1 Scenario Definition

If a Web service starts out uninternationalized and is later internationalized, it must be re-deployed as a separate service because the original service contract has changed.

2.8.1.2 Description

The web services developer is solely responsible for supplying the fields, logic, and semantics that will be used to achieve i18n capabilities. Each service will vary in its approach and may not bother to supply a suitable mechanism. Without guidance from the client, assumptions have to be made that are unsuitable. For example, the locale of the server may be used to format the response. When the service is internationalized, the only option is to ask for locale as an additional input, changing the service contract.

There is an important functional and semantic difference between a field supplied in the actual service invocation (that is, as part of the data) and one supplied in the envelope (that is, as part of the protocol) because when supplied as part of the data, developers must always take care to create, populate, read, and process the fields. Internationalization of an existing service therefore takes the form of deploying a new service (since the inputs have changed).

By contrast, if locale and language preferences are part of the "context" (in the envelope, for example), the developer gains several advantages. First, both the provider and the service can read the locale and language preference. (The service must be provided with a specific API to obtain the locale and language from the provider, or it can be silently managed by the provider.) Services that require external environmental changes to activate their locale-sensitivity can have the provider perform this processing for them. Multiple services in the same "chain" can inherit the same locale and language context. Most important, though, the client-side environment can be optimized to provide the locale and language preferences of the end user automatically, without developers having to write code to obtain the values and populate the inputs of the Web Service. In addition, Web Service authors can add international or multi-language support to services after initial deployment without changing service descriptors (WSDL and XSD) that may already be in wide use.

2.8.2 Communicating Available Options

2.8.2.1 Scenario Definition

There is no way for the service to communicate what language and formatting options are available.

2.8.2.2 Description

If a Web service requires that a language, locale, or formatting preference in a service description (WSDL), how can the sender know what values will have meaning at the receiver. For example, POSIX locales for a C program are very different than (say) Windows LCID values.

As a result, developers of internationalized Web services (especially those that support multi-lingual operations - that is, servers that can provide responses in a variety of human languages and dialects) have to provide the ability to external users, whose platforms and programming languages may be maximally different than their own, to know what options the service supports.

2.9 Template

2.9.1 Title

2.9.1.1 Scenario Definition
2.9.1.2 Description

3 Use Case

Editorial note: KN2002-12-10
Use Case is added based on usage scenarios. e.g. Flight Schedule, Accounting Data

A References (Non-Normative)

[WSA]
W3C Working Draft "Web Services Architecture", Michael Champion, Chris Ferris, Eric Newcomer, David Orchard, 14 November 2002 (See http://www.w3.org/TR/2002/WD-ws-arch-20021114/.)
[WSAR]
W3C Working Draft "Web Services Architecture Requirements", Daniel Austin, Abbie Barbir, Christopher Ferris, Sharad Garg, 14 November 2002 (See http://www.w3.org/TR/2002/WD-wsa-reqs-20021114.)
[WSAUS]
W3C Working Draft "Web Services Architecture Usage Scenarios", Hugo Haas, David Orchard, 30 July 2002 (See http://www.w3.org/TR/2002/WD-ws-arch-scenarios-20020730/.)
[WSAG]
W3C Working Draft "Web Services Glossary", Allen Brown, Hugo Haas, 14 November 2002 (See http://www.w3.org/TR/2002/WD-ws-gloss-20021114/.)
[SOAP-0]
W3C Working Draft "SOAP Version 1.2 Part 0: Primer", Nilo Mitra, 26 June 2002 (See http://www.w3.org/TR/2002/WD-soap12-part0-20020626/.)
[SOAP-1]
W3C Working Draft "SOAP Version 1.2 Part 1: Messaging Framework", Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau, Henrik Frystyk Nielsen, 26 June 2002 (See http://www.w3.org/TR/2002/WD-soap12-part1-20020626/.)
[SOAP-2]
W3C Working Draft "SOAP Version 1.2 Part 2: Adjuncts", Martin Gudgin, Marc Hadley, Jean-Jacques Moreau, Henrik Frystyk Nielsen, 26 June 2002 (See http://www.w3.org/TR/2002/WD-soap12-part2-20020626/.)
[SOAP-AF]
W3C Working Draft "SOAP 1.2 Attachment Feature", Henrik Frystyk Nielsen, Hervé Ruellan, 24 September 2002 (See http://www.w3.org/TR/2002/WD-soap12-af-20020924/.)
[SOAP-EB]
W3C Note "SOAP Version 1.2 Email Binding", Highland Mary Mountain, Jacek Kopecky, Stuart Williams, Glen Daniels, Noah Mendelsohn, 3 July 2002 (See http://www.w3.org/TR/2002/NOTE-soap12-email-20020703.)
[WSDL-V12]
W3C Working Draft "Web Services Description Language (WSDL) Version 1.2", Roberto Chinnici, Martin Gudgin, Jean-Jacques Moreau, Sanjiva Weerawarana, 9 July 2002 (See http://www.w3.org/TR/2002/WD-wsdl12-20020709/.)
[WSDL-B]
W3C Working Draft "Web Services Description Language (WSDL) Version 1.2: Bindings", Jean-Jacques Moreau, Jeffrey Schlimmer, 9 July 2002 (See http://www.w3.org/TR/2002/WD-wsdl12-bindings-20020709/.)
[XML]
W3C Recommendation "Extensible Markup Language (XML) 1.0 (Second Edition)", Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 6 October 2000 (See http://www.w3.org/TR/2000/REC-xml-20001006.)
[CHARMOD]
W3C Working Draft "Character Model for the World Wide Web 1.0", Martin J. Dürst, François Yergeau, Richard Ishida, Misha Wolf, Asmus Freytag, Tex Texin, 30 April 2002 (See http://www.w3.org/TR/2002/WD-charmod-20020430/.)
[WSI-BP]
WS-I Working Group Draft Basic Profile Version 1.0, Keith Ballinger, David Ehnebuske, Martin Gudgin,Mark Nottingham, Prasad Yendluri, 2002/10/08 (See http://www.ws-i.org/Profiles/Basic/2002-10/BasicProfile-1.0-WGD.htm.)
[XML-JP]
W3C Note "XML Japanese profile", MURATA Makoto, 14 April 2000 (See http://www.w3.org/TR/2000/NOTE-japanese-xml-20000414/.)
[RFC2616]
Request for Comments: 2616 "Hypertext Transfer Protocol -- HTTP/1.1", R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, June 1999 (See http://www.ietf.org/rfc/rfc2616.txt.)
[XMLS-2]
W3C Recommendation "XML Schema Part 2: Datatypes", Paul V. Biron, Ashok Malhotra, 02 May 2001 (See http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.)
[UDDI]
"UDDI Version 3.0 Published Specification", Tom Bellwood, Luc Clément, David Ehnebuske, Andrew Hately, Maryann Hondo, Yin Leng Husband, Karsten Januszewski, Sam Lee, Barbara McKee, Joel Munter, Claus von Riegen, 19 July 2002 (See http://uddi.org/pubs/uddi_v3.htm.)
[RFC2279]
IETF (Internet Engineering Task Force). RFC 2279: UTF-8, a transformation format of ISO 10646, ed. F. Yergeau, 1998 (See http://www.ietf.org/rfc/rfc2279.txt.)
[RFC2781]
IETF (Internet Engineering Task Force). RFC 2781: UTF-16, an encoding of ISO 10646, ed. P. Hoffman, F. Yergeau. 2000 (See http://www.ietf.org/rfc/rfc2781.txt.)
[XHTML]
W3C Recommendation "XHTML 1.0 The Extensible HyperText Markup Language (Second Edition)", 26 January 2000, revised 1 August 2002 (See http://www.w3.org/TR/xhtml1/.)
[XFORMS]
W3C Candidate Recommendation "XForms 1.0", Micah Dubinko, Leigh L. Klotz, Jr., Roland Merrick, T. V. Raman, 12 November 2002 (See http://www.w3.org/TR/xforms/.)

B Acknowledgements (Non-Normative)

This document is the work of the Web Services Task Force of the W3C Internationalization Working Group.

C Heisei (Non-Normative)

The imperial Calendar is commonly used in Japan. Heisei is the current era, and it started on January 8th, 1989. Year 2002 is Year Heisei 14. Showa is the previous era, which ended on January 7th, 1989 or Showa 64.