This page is a subpage of CMDI 1.2

Localised documentation

An executive summary is available at CMDI 1.2/Cues/Localised documentation/Summary

The issue

In CMDI 1.1 documentation on elements has no language property and there can be only one instance per element; hence, there is no way to provide documentation in multiple languages. For localised applications, it would be good to have this option so that the application can show documentation in the preferred language if available (as is the case with descriptions in ISOcat).

Proposed solutions

Depending on how documentation texts will be represented in component specifications, add an (additional) attribute to the documented attribute, component or element (see Documentation on Components and Attributes). The most elegant solution would be to refactor the current Documentation attribute into a child element with the xml:lang attribute. In the XSD this would be transformed into an xs:annotation element.

Pros

Cons

If using child element/xs:annotation approach: not so much backward compatible (place of documentation changes), relatively large change for tools (but not critical as long as they ignore the new element)

Centre impact

• Tools that use the documentation (presumably only editors: Arbil, Proforma?)
• No impact on instances

Implementation examples

Component specification example:

<CMD_Component name="Actor" CardinalityMin="0" CardinalityMax="unbounded" ComponentId="ex_compid_actor">

  <Documentation xml:lang="en">This is a person or entity that plays a role in the resource</Documentation>
  <Documentation xml:lang="nl">Dit is een persoon of entiteit die een rol speelt in de beschreven bron</Documentation>

  <CMD_Element name="firstName" ValueScheme="string" DisplayPriority="0" CardinalityMax="1">

    <Documentation xml:lang="en">This is the firstname of a person</Documentation>
    <Documentation xml:lang="nl">Dit is de voornaam van een persoon</Documentation>

    <AttributeList>
      <Attribute>
        <Name>nickname</Name>
        <Type>string</Type>
        <Documentation xml:lang="nl">Bijnaam van een persoon</Documentation>
      </Attribute>
    </AttributeList>

  </CMD_Element>
</CMD_Component>

Schema example for the above specification (showing only for firstName element):

 ...
 <xs:element name="firstName" maxOccurs="1"
             ann:documentation="This is the firstname of a person"
             ann:displaypriority="0">
  <xs:annotation>
   <xs:documentation xml:lang="en">This is the firstname of a person</xs:documentation>
   <xs:documentation xml:lang="nl">Dit is de voornaam van een persoon</xs:documentation>
  </xs:annotation>
  <xs:complexType>
   <xs:simpleContent>
    <xs:extension base="xs:string">
     <xs:attribute name="nickname" type="xs:string">
      <xs:annotation>
       <xs:documentation xml:lang="nl">Bijnaam van een persoon</xs:documentation>
      </xs:annotation>
     </xs:attribute>
     ...

Tickets

Tickets in the CMDI 1.2 milestone with the keyword localiseddocumentation:

Ticket	Summary	Owner	Component	Priority	Status
No tickets found

Discussion

Discuss the topic in general below this point