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.
Recommended best practice is to use locale neutral formatted data with additional attributes. Final locale sensitive formatting should be done in a presentation layer closest to the receiver. Time and date are sent using ISO-8601 canonical formatting (YYYY-MM-DD, HH:MM:SS). For this example, airline departure time is sent in local time as opposed to Universal (UTC) time, as this is most acceptable for airline schedule data. If the data were sent directly from application to application, it should send time in UTC format, with a local airport timezone presented in time difference from UTC.
<?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.
<?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:time>13:30:00</c:time> </departuretime> </c:getAvailableFlightResponse> </env:Body> </env:Envelope>
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. This is recommended best practice for commerce systems that must transport transaction information.
<?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>
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.
This is an acceptable practice when presenting data from legacy commerce systems through Web services, for instance a Japanese retail or banking site, which conducts all transactions in Japanese Yen providing data to an international commerce system.
<?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>
Applies to: Web services in 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 dates to a Japanese receiver, the Japanese sender may wish to send the data in a Japanese date format as required for government records, such as H13-5-31(H stands for the Heisei era; see Appendix C Heisei).
<?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-05-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 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 a requirement applicable for interface definitions in WSDL?
Editorial note: KN | 2002-12-10 |
Possible datatype: Telephone number, Post code etc. Needs feasibility assessment. |
There is a difference between data types such as telephone number, address elements, post code, forms of address, 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. It is the responsibility of the presentation layer (outside of SOAP) to properly format locale sensitive data.
WSDL can be used to set a locale header and used as a wrapper for data being sent from a legacy system, such as sending address information from the Russian Post Office for use by an international postal system, where all data sent is from only one locale (ru_RU).
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 [WSA].
Service "A" is defined as a service that returns status text and deployed on Providers "A1", "A2", and "A3" in different language configurations (locales).
Provider "B" polls Service "A" on each machine and caches the results.
Service "B" is defined as a process that returns cached results and is deployed on Provider "B".
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 negotiated 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 if good I18n priciples are not used and proper tracking of source data locale and Requester locale.
Best practice solution is for Provider "B" to store results from each Provider in Service "A", tracking locales of the results. Fault messages should be sent to "B" in all Provider Languages. "C" Requesters must identify the locale of expected results.
For a Web service "wrapper" to a legacy client/server application, the SOAP header could be used for locale negotiation between Requesters and Service.
See I-007 for a similar problem.
Searching for Web services depending on language or culture.
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.
Using xml:lang and multiple entries, a Service Provider can publish text information about their service in multiple languages. The name, description, address, and personName UDDI elements MAY be adorned with the xml:lang attribute to indicate the language in which their content is expressed. The policyDescription element contains a description of the effect of the policy implementation. This element can be adorned with the xml:lang attribute and can appear multiple times to allow for translations of the policy description. Providers are encouraged to do this for target language markets that their service may support.
Ideally, the entity names in UDDI should also provide and Alternate Name in RFC-2277 default language, readable in English. This provides a fall back mechanism to allow a search to identify services even if the named contents may be in a script that is not readable by the entity doing the search.
(From the UDDI Spec)
The following shows an example of romanization where the primary name of the business (a Chinese flower shop) is in Chinese, and its alternative name is a romanization:
<businessEntity . . . >
........
<name xml:lang="zh">黄河花店</name>
<name xml:lang="en">Huang He Hwa Dian</name>
.....
</businessEntity>
The following shows an example of transliteration where the primary name of the business is in Chinese, and is a transliteration of its alternative English name:
<businessEntity . . . >
........
<name xml:lang="zh">康柏電腦股份有限公司</name>
<name xml:lang="en">Compaq Computer Taiwan Limited</name>
.....
</businessEntity>
The following example XML fragment shows an address written in two languages, English and Chinese, as indicated by the xml:lang attribute:
<address useType=”Sales office” xml:lang="en" tModelKey=”uddi:…”>
<addressLine>7 F</addressLine>
<addressLine>No. 245 </addressLine>
<addressLine>Sec. 1</addressLine>
<addressLine>Tunhua South Road</addressLine>
<addressLine>Taipei </addressLine>
</address>
</address><address useType=”Sales office” xml:lang="zh" tModelKey=”uddi:…”>
<addressLine> 台北市 </addressLine>
<addressLine> 敦化南路</addressLine>
<addressLine> 一段</addressLine>
<addressLine> 245 號</addressLine>
<addressLine> 7 樓</addressLine>
…
</address>
Editorial note: KN | 2002/12/13 |
UDDI provides TAXONOMY based on the ISO 3166 Geographic Code System. |
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?
Currently, this is implementation defined? Is there an RFC or W3C source we can reference? Fall back mechanism in HTML?
Editorial note: F2F | 2002-11-23 |
Need to more clearly define this scenario and provide examples. |