[security-services] Issue: error messages in multiple natural languages

["Eve L. Maler" <eve.maler@sun.com>]

Completing an action item I took in the 29 January meeting:

In core-25, StatusMessage is defined (Section 3.4.3.3, lines 1183-1187) as 
being of type string.  Its inclusion in the Status element (lines 
1114-1115) allows multiple occurrences, that is, zero or more messages per 
status returned.  In the call on Tuesday we discussed the potential need to 
allow for multiple natural-language versions of status messages.

If the StatusMessage element can't contain markup, then it makes it hard 
for someone to provide, say, both English and Japanese versions of an error 
message.  Here are two obvious different ways to do this, both using the 
native xml:lang attribute to indicate the language in which the message is 
written.

(See also a possible SEPARATE issue at the bottom of this message.)

                     ================================

Option 1: Multiple StatusMessage elements, each with language indicated

Currently, multiple StatusMessages are already allowed, but we say nothing 
in the spec to explain how they're supposed to be used or interpreted.  The 
description just says (lines 1105-1106):

<StatusMessage> [Any Number]
   A message which MAY be returned to an operator.

(Hmm, not sure what "operator" means here..)  This option would place a 
specific interpretation on the appearance of multiple StatusMessage 
elements related to language differentiation, and would allow for an 
optional xml:lang attribute on the element:

<StatusMessage> [Zero or more]
   A natural-language message explaining the status in a human-readable 
way.  If more than one <StatusMessage> element is provided, the messages 
are natural-language equivalents of each other; in this case, the xml:lang 
attribute SHOULD be provided on each element.

<element name="StatusMessage">
   <complexType>
     <simpleContent>
       <extension base="string">
         <attribute name="xml:lang" type="language"/>
       </extension>
     </simpleContent>
   </complexType>
</element>

I prefer this option because it has less markup overhead, as long as the 
multiple <StatusMessage> elements already allowed in the schema weren't 
intended to have some other meaning instead (in which case, that meaning 
needs to be documented).  If they weren't, then if this option *isn't* 
picked, I think we need to shut down multiple occurrences of 
<StatusMessage>, changing it to minOccurs="0" and maxOccurs="1".

                     ================================

Option 2: One StatusMessage element, with partitioned content indicating 
language

This option isn't all that different from option 1.  It would invent a new 
subelement to go into the content of <StatusMessage> like so:

<StatusMessage>
   A natural-language message explaining the status in a human-readable 
way.  It contains one or more <MessageText> elements, each providing 
different natural-language equivalents of the same message.

<element name="StatusMessage" type="StatusMessageType" />
<complexType name="StatusMessageType">
   <sequence>
     <element ref="MessageText" maxOccurs="unbounded" />
   </sequence>
</complexType>

<MessageText>
   The text of the status message.  If more than one <MessageText> element 
is provided, the messages are natural-language equivalents of each other; 
in this case, the xml:lang attribute SHOULD be provided on each element.

<element name="MessageText">
   <complexType>
     <simpleContent>
       <extension base="string">
         <attribute name="xml:lang" type="language"/>
       </extension>
     </simpleContent>
   </complexType>
</element>

I think this option is necessary *if* multiple occurrences of 
<StatusMessage> were already intended to have some other meaning.  If they 
weren't, then I prefer option 1.

                     ================================

Digression on xml:lang

You can read about this attribute here:

Brief description of the xml: namespace:
   http://www.w3.org/XML/1998/namespace.html
Section of the XML spec itself that defines xml:lang:
   http://www.w3.org/TR/REC-xml#sec-lang-tag

There is also a non-normative but helpful schema module that defines the 
items in the xml: namespace.  You can find it here:

   http://www.w3.org/XML/1998/namespace.xsd

This schema module can be useful if you want to slurp those definitions 
into the SAML schemas to make sure that SAML instances can be fully 
validated.  Alternatively, we can legally cook up our own schema code for 
this as shown in the two options above, which would avoid importing another 
schema module into both of ours, with attendant code and documentation.  If 
we do that,  note that we'll still need to declare the xml: namespace at 
the tops of our schema modules.

                     ================================

Final thoughts

Even if the issue of multiple-language support is deferred until a future 
release, I believe that <StatusMessage> and the fact that it's repeatable 
is underspecified at the moment.  I would like to see it restricted to an 
optional single occurrence, or alternatively, I would like to have its 
semantics explained when multiple occurrences are used.  This can be listed 
as a separate issue if you like.

	Eve
--
Eve Maler                                    +1 781 442 3190
Sun Microsystems XML Technology Center   eve.maler @ sun.com