GetTimeService can be written as a locale-neutral service. Time of day, although it is presented with different formats around the world, is measured the same way everywhere and a standardized single frame of reference is available to be used. So a service request could return with a response that included the current UTC (Coordinated Universal Time) time in ISO 8601 format: hh:mm:ss.sss, i.e. as an XML Schema Part 2: Datatypes time type.

Any application (i.e. a consumer) that triggers an event causing the GetTimeService request to be sent to a Service Provider, can transform the result into a local or other time format, including perhaps shifting the time into the local time zone. With this proposed implementation, from the requester agent to the service provider, the service and back to the requester agent, the request document and its service implementation are entirely independent of the locale of the client, the host, and the implementer. Hence the name locale-neutral.

Of course, the request could also be implemented with dependencies on locale of the client or the host and this would complicate implementation and increase the probability of errors in making requests, deploying the service, or implementing the service.

Language neutral services, being the default, do not generally announce themselves in their service contracts, although (other scenarios apply here).

The Web services description does not require any extra information in order to perform its operations or communicate its capabilities. Therefore no additional fields beyond those required by the actual service implementation should be defined in any of the bindings or operations.

The implementer should consider adding a language tag to any operation fault elements to show what language to expect fault messages to be generated in.

No additional attributes or information is required for this pattern.

Fault messages may be generated in a variety of languages simultaneously. If the transport provides a way of determining the requester agent's preferred language (such as the Accept-Language header in HTTP), then these preferences should be used first. In all cases, a "message of last resort" should be generated, which generally should be in the language and locale of the provider agent or the language most preferred by the administrator of that system (since that is who will have to debug any service requests against the system). Many systems are run in default locales, which often default to the English language. This should be a consideration in configuring the system.

A service provider is in 3 country markets: U.S., Japan, and Germany. Each market is supported by a local warehouse. One of the services that is provided indicates availability of parts. For a given part number, the following information is returned: part number, quantity, language, description, size, list price.

If all of the information was maintained in a single database one might see entries like:

@@@@add some native Japanese and german language entries.

However, this company has not yet implemented a worldwide inventory application and instead each warehouse maintains its inventory in a separate and independent database and uses different applications to manage inventory. In fact, the Japanese warehouse is the only one that uses a system that supports the Japanese language. Because of its support for Japanese and its use of legacy encodings instead of Unicode, the Japanese system cannot properly support German text.

The service provider has implemented a service, GetProductInventory.

The input (inbound message) takes a part number or part ID. The output (outbound message) returns the following information: part no., quantity, language, description, size, list price.

An implementation decision might be taken to provide separate Web services for each warehouse. Customers on each continent will be directed to a particular web service that returns the information from the appropriate warehouse. This pattern is service-determined as it reflects the inherent nature of the service in each part of the world. (That is the German warehouse supports clients in Germany.)

This example also demonstrates the "service determined" type of limitation: it's capabilities are limited by its use of legacy applications. If the databases were consolidated and suitable shipping facilities were made available, the service could still not offer product from any warehouse to any client. The Japanese clients using the Japanese service provider would not be able to see all of the potential German beer names. (They could only see them if the names were transliterated to Japanese or a subset of the Japanese legacy encoding, such as 7-bit ASCII.)

There are several sub-patterns for this.

The service may be written to assume a specific locale or language setting or the server which hosts the service or provider agent may be statically configured to use a specific locale. This is generally a poor choice, since it implies a non-internationalized implementation to start with. However, legacy code or other choices may require this pattern and not be in the control of the Web service.

The service may be enabled for or capable of internationalized operation, but it may be configured to process all requests in just a few (or, more likely, just one) language or locale. This allows the service to be deployed to many locales or for it to serve several markets simultaneously, depending on how the service and/or its provider agent is configured.

Service determined language or locale matching is a pattern that is useful when the service's performance is explicitly linked to what it does. For example, a service that returns whether the New York Stock Exchange will be open or closed on a particular day is strongly linked to the holiday schedule in the USA. The service may be written in such a way that it can also be used by other exchanges in other countries, but the specific service might be written simply to support the needs of this one use.

Similar to that of Language Neutral, except that the server's local language preference is expected to affect processing. In most cases the difference between Language Neutral and Service Defined is that the latter returns values that have elements consisting of natural language text or are otherwise locale affected, whereas a Language Neutral service returns values that can be formatted entirely by the requester agent or requester.

The Web services description may provide an optional header field in the operation output element defining the natural language used by the service at execution time. Since this value is at least partially machine dependent, the value probably should not be set in the actual service description. Instead the soap:header or equivalent field should merely be defined as being available. If the service uses an enumerated set of languages, it might be wise to ensure that the actual language used is always passed back in any output.

This Web service pattern is generally similar to that of Language Neutral. Processes that are language or locale affected may retrieve their settings from the default machine settings and the SOAP Processor generally need not provide any special functionality to activate or achieve this.

Faults are generated as with Language Neutral, except that the service specific language should also be generated after any user specified value, but before that of the SOAP Processor, assuming that these three are all different values and that all are available.

If the service determined example (GetProductInventory) were upgraded so that data was globally accessible, then the pattern could be changed to the client-influenced pattern. In this case, the Web service GetProductInventory, could return information about inventory from all warehouses or any specific warehouse, but would take advantage of the user's language and locale preferences to influence how choices are returned, the ordering of the choices, and even which choices are displayed.

For example, a user that has a Japanese language preference might see only the inventory counts for the products available in the Japanese warehouse, with Japanese language description. Although the locale-influenced web service may return the "best" responses for a majority of users, it may be wrong for some percentage, which on the web may be a large number of users. For example, Japanese-speaking clients in U.S. would be better served (perhaps) by inventory from the U.S. warehouse.

A more precise web service design would make the selections of warehouse and description language, currency, etc. explicit. However, it is not always possible to present the client all of the information up front for them to make good choices on a form with many explicit options. So client-influenced patterns are often used for this purpose.

In this usage pattern, the service description and actual execution should be designed to allow the requester agent to pass the most appropriate value for the specific invocation of the service.

Both inbound and outbound headers define a attribute bound to type xsd:language and labelled with an xml:lang element. The inbound header should allow multiple values to be passed, in case the first preference is not available. The outbound value should be a single discrete value: that actually used by the service at execution time.

Inbound and outbound headers optionally take the element defined in the WSDL. If not present, the SOAP Processor's local language preference is used. Outbound headers should reflect as accurately as possible the actual value used in performing the processing. This may vary from that specified by the user according to the rules in RFC3066 (or its successor). If no match may be obtained, the results will be implementation defined--the service may generate a fault if processing can go no further, but most implementations will probably use the current provider agent's default locale for the value.

Fault messages should be generated with the requester's preferred language(s), in order by preference, followed by the provider agent's default language.

The service requester needs to select a matching language from the list of fault reasons returned by the service provider. This scenario illustrates an issue that implementations have to take into account.

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

If the requester prefers "en-GB", then neither string will match directly 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 the assumption that languages with common prefixes are mutually understandable. If the requester prefers "ja", then selecting the best fallback is even more difficult.

Applies to: SOAP, or an extension of SOAP

Service Oriented Architecture Derivative Patterns One Way Message

Service "B" should return a message in a language that matches Requester "B"'s language preference (so that the administrator of that system can use it). In addition, if Requester "A"'s preferences are available to Requester "B" (that is, Service "A" got the preferences as part of its input or via an external mechanism such as the transport), then Requester "A"'s language preference should be included in the SOAP fault reason text.

For example:

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

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

Applies to: SOAP, SOAP interface of software systems

A sender and a receiver wish to use a legacy (i.e. not Unicode-based) encoding. This scenario provides an example of good practice, but using an Unicode-based encoding (see ) is preferable and Web service implementers should avoid legacy encodings wherever possible to ensure interoperability.

This scenario is divided into three aspects.

When a sender sends a SOAP message in a legacy encoding to a receiver, the receiver may not be able to accept the legacy encoding. In order to use a legacy encoding in a SOAP message, the sender needs to know beforehand whether the receiver is able to accept the legacy encoding in question.

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.

The XML Japanese Profile describes that using legacy encodings such as Shift_JIS cannot provide complete interoperability in information interchange; there are slight differences among platforms in the mapping tables they use for this and similar encodings.

Applies to: SOAP, SOAP interface of software systems

A service defines a language preference. The service is then chained.

Service "A" defines an optional header, as in section 2.3.3, containing a language request field. This service is deployed.

Service "B" defines a service that includes a call to Service "A", but does not define a natural language header.

A requester calls service "B" with the arguments provided by service "B". Service "A" therefore receives no language preference or Server "B"s provider's preference.

Applies to: SOAP, or an extension of SOAP

FaultReason must substitute locale-sensitive data into text message.

Service "A" is defined on Provider "A". A fault is generated during invocation that returns a faultReason that includes values for which the presentation depends on locale.

The provider should format substitutions in each message according to the language (and implied locale) of the message, not according to the locale of the provider or service. In the case of Language Neutral or Service Determined patterns, it may not be possible to generate a message in the user's preferred language (or the preference may not be available). In these cases, the message should follow the language preference of the provider or service host.

Applies to: SOAP, or an extension of SOAP

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

Some protocols, such as HTTP or, to a lesser extent, SMTP, contain headers or other information that can be used to communicate the requester's language preference. If a service is designed to be wholly or partially sensitive to the requester's language preference, it should include an optional header in the Web service description with the name "lang" which uses the type xsd:language. This value should be used preferentially by the service when deciding on the language preference of the requester. If the value is not supplied or the value is not installed (available) locally, then the provider may also choose to process information provided by the transport protocol. If no values are available or supplied, then the provider may choose some reasonable default to use in the service.

HeaderFault vs. Fault

Provider "A" should, if possible, try to resolve any reason Text elements into the languages requested by Requester "A". In some cases this may not be possible because the language in question is not available or the design of the error handling subsystem does not allow multiple language resolution of the fault. In this case, Provider "A" should return the message provided by Service "A" and labeled with the local language (or the language of the actual message, if known).

Caching may affect the results of language negotiation. (This usage scenario is still work in progress.)

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.

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) 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.

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.

On the other hand, dates and date-time values are affected by the user's location (timezone). 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 always ensure locale-neutral data semantics.

For example, a Web service that returns whether the New York Stock Exchange is open or closed on a specific day can accept a date like 2002-05-31 as location independent--the exchange is either open or closed that day. However, for example, a service that places a "limit order" (that is, a purchase of stock that has specific limits on it, one of which may be an expiration date if the other limits are not met) might tie the expiration date to the specific time the market closes in New York that day rather than to an arbitrary other timezone.

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.

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

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.

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.

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

Applies to: Web Services in general

A service is designed around a single currency and therefore did not associate financial data with currency symbol or codes. However, the responses from this service may in turn be used by multicurrency services or incorporated into other messages. Therefore the response should be modified to identify the currency used by the service. There are 3 possible solutions. Two involve modifying the message format. The message can be changed so that a currency element is added to any node that has financial data elements. An alternative is to provide the currency as an attribute for any financial data. However, it may be unacceptable to change the XML message format used by the service. A third alternative is to indicate the currency used throughout the message in the SOAP header.

The following example demonstrates multiple currency data transmission in a SOAP message and the currency code being provided in a separate element along with the value.

The following is an example which has the default currency in SOAP header. It is also possible to specify the default currency attribute in SOAP body instead of SOAP header.

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

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.

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 ) to the receiver.

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?

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

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

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.

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

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.

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

Data sent by a sender is formatted by the receiver according to format(s) provided by the sender. This is different from the scenarios "" or "" in that the center of decision and the actual execution of the formatting are separated. Scenarios "" or "" 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.

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

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

Presentation result for user interface is:

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

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

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)

Using an opaque identifier to identify a locale.

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.

Searching for Web services depending on language or culture.

Repositories and search-able meta-data (such as 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.

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

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

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

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)

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.

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

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.

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.

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.

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.

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

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.