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 <address> element, contained in the businessEntity structure, contains a simple list of <addressLine> elements.
To expose an address’ structure and meaning, virtual keyedReference elements are employed. This is done by adorning the <address> element with a tModelKey attribute and use of the keyName/keyValue attribute pair for each <addressLine> element.
Additionally, the UDDI Business Registry has a canonical tModel, ubr-uddi-org:postalAddress, that identifies a canonical postal address structure with common address sub-elements (e.g. states, cities). This canonical address structure describes address data via name/code pairs, enabling each common address sub-element to be identified by name or code.
The following example XML fragment shows how the application of tModelKey, keyName and keyValue attributes to <address>, in conjunction with the use of address sub-element names and codes defined by the ubr-uddi-org:postalAddress tModel, allows the structure and meaning of a contact’s address within a businessEntity to be derivable programmatically:
<address useType=”Sales office” tModelKey=”uddi:ubr.uddi.org:postalAddress”>
<addressLine keyName=”Street” keyValue=”60”>Alexanderplatz</addressLine>
<addressLine keyName=”House number” keyValue=”70”>12</addressLine>
…
<addressLine keyName=”Country” keyValue=”20”>Deutschland</addressLine>
</address>
The following example XML fragment shows an address in two languages where the sequence of the address lines differ according to the language used. With the use of keyName/KeyValue pair together with the codes assigned in the ubr-uddi-org:postalAddress tModel, it is possible to determine the address semantics programmatically in spite of the difference in address sequence :
<address useType=”Sales office” xml:lang="en" tModelKey=”uddi:ubr.uddi.org:postalAddress”>
<addressLine keyName=”Floor” keyValue=”100”>7 F</addressLine>
<addressLine keyName=”House Number” keyValue=”70”>No. 245 </addressLine>
<addressLine keyName=”District” keyValue=”50”>Sec. 1</addressLine>
<addressLine keyName=”Street” keyValue=”60”>Tunhua South Road</addressLine>
<addressLine keyName=”City” keyValue=”40”>Taipei </addressLine>
</address>
</address><address useType=”Sales office” xml:lang="zh" tModelKey=”uddi:ubr.uddi.org:postalAddress”>
<addressLine keyName=”City” keyValue=”40”> 台北市 </addressLine>
<addressLine keyName=”Street” keyValue=”60”> 敦化南路</addressLine>
<addressLine keyName=”District” keyValue=”50”> 一段</addressLine>
<addressLine keyName=”House Number” keyValue=”70”> 245 號</addressLine>
<addressLine keyName=”Floor” keyValue=”100”> 7 樓</addressLine>
…
</address>
As there is a large variation in address sub-elements of different countries, the defined canonical address structure does not attempt to include all possible address sub-elements of all countries. Freeform address lines are therefore supported in the <address> element.
The usage of the canonical address structure is optional, but recommended, for both publishers of business entities and developers of GUIs of UDDI publishing services.
The following shows an example of use of multiple name elements to support a multi-script language and also the use of acronym. In the example, the first <name> element is the primary name of the business (a Japanese flower shop) in Japanese Kanji. The second <name> element is the business’ name transliterated into Japanese Katakana. The third <name> element gives the business’ full English name, and the fourth <name> element gives its English acronym:
<businessEntity . . . >
........
<name xml:lang="ja">日本生花店</name>
<name xml:lang="ja">ニッポンセイカテン</name>
<name xml:lang="en">NIPPON FLOWERS </name>
<name xml:lang="en">NF</name>
.....
</businessEntity>
Where multiple name elements are published, the first name element is treated as the primary name, which is the name by which a business would be searched and sorted in the case of multiply-named businesses. Client applications may use this knowledge to assist in optional rendering of a publisher’s primary name or all alternative names.
| 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. | |