xNAL usage guidelines

Extended information and usage examples for DITA bookmap metadata elements associated with OASIS xNAL Standard (extensible Name and Address Language).

DITA bookmaps use a set of elements associated with a subset of the OASIS extensible Name and Address Language (xNAL) specification (Version 2) to denote name and address information related to persons and organizations.

While the elements share element names, and the expectation is that content written using this type of metadata is be straightforward to transform, the element name pairs do not share content models. The difference in content models reflects the different purposes of the two standards. The purpose of the name and address elements in DITA is to identify persons or organizations associated with the creation of a document; the purpose of the name and address elements in xNAL is to support customer resource management.

The examples shown after the table provide sample tagging methods for name and address information, using the DITA elements associated with xNAL.

DITA elements associated with xNAL elements

The set of bookmap elements associated with elements from the OASIS extensible Name and Address Language (xNAL) standard are listed in the table below.

Table 1. DITA elements associated with xNAL elements
`<addressdetails>`	`<honorific>`	`<otherinfo>`
`<administrativearea>`	`<lastname>`	`<person>`
`<authorinformation>`	`<locality>`	`<personinfo>`
`<contactnumber>`	`<localityname>`	`<personname>`
`<contactnumbers>`	`<middlename>`	`<postalcode>`
`<country>`	`<namedetails>`	`<thoroughfare>`
`<emailaddress>`	`<organization>`	`<url>`
`<emailaddresses>`	`<organizationinfo>`	`<urls>`
`<firstname>`	`<organizationname>`
`<generationidentifier>`	`<organizationnamedetails>`

Example 1: Tagging personal information in DITA

This example shows a way to tag the following personal name and description.

Mr. Ram V. Kumar Jr.
Chief Technologist
MSI Business Solutions

<authorinformation>
  <personinfo>
    <namedetails>
      <personname>
        <honorific>Mr.</honorific>
        <firstname>Ram</firstname>
        <middlename>V.</middlename>
        <lastname>Kumar</lastname>
        <generationidentifier>Jr.</generationidentifier>
        <otherinfo>Chief Technologist</otherinfo>
      </personname>
    </namedetails>
  </personinfo>
  <organizationinfo>
    <namedetails>
      <organizationnamedetails>
        <organizationname>MSI Business Solutions</organizationname>
      </organizationnamedetails>
    </namedetails>
  </organizationinfo>
</authorinformation>

Example 2: Tagging address information in DITA

This example shows a way to tag the following address.

23 Archer St.
Chatsworth
NSW 2067
Australia

<addressdetails>
  <thoroughfare>123 Archer St.</thoroughfare>
  <locality>
    <localityname>Chatsworth</localityname>
    <postalcode>2067</postalcode>
  </locality>
  <administrativearea>NSW</administrativearea>
  <country>Australia</country>
</addressdetails>

Example 3: Tagging complex name and address information in DITA

This example shows two ways to tag a fairly complex collection of personal, organizational, and address information.

Mr. Samuel L. Johnson Jr.
Chief Technologist
c/o XYZ Corporation
52 New Main St.
Carrboro, NC 27510 USA
email: johnson@example.com
phone: 919-555-7987

This method tags all the organizational information as associated with the identified person.

<personinfo>
   <namedetails>
      <personname>
          <firstname>Samuel</firstname>
          <middlename>L.</middlename>
          <lastname>Johnson</lastname>
          <generationidentifier>Jr.</generationidentifier>
          <otherinfo>Chief Technologist</otherinfo>
          <otherinfo>c/o XYZ Corporation </otherinfo>
      </personname>
   </namedetails>
   <addressdetails>
      <thoroughfare>52 New Main St.</thoroughfare>
      <locality>
         <localityname>Carrboro</localityname>
         <postalcode>27510</postalcode>
      </locality>
      <administrativearea>NC</administrativearea>
      <country>USA</country>
   </addressdetails>
   <contactnumbers>
      <contactnumber>919-555-7987</contactnumber>
   </contactnumbers>
   <emailaddresses>
      <emailaddress>johnson@example.com</emailaddress>
   </emailaddresses>
</personinfo>

The following method separates the person and organization information. It might be used if it were necessary to associate address information with organizations rather than persons.

<authorinformation>
  <personinfo>
    <namedetails>
      <personname>
        <firstname>Samuel</firstname>
        <middlename>L.</middlename>
        <lastname>Johnson</lastname>
        <generationidentifier>Jr.</generationidentifier>
        <otherinfo>Chief Technologist</otherinfo>
      </personname>
    </namedetails>
    <contactnumbers>
      <contactnumber>919-555-7987</contactnumber>
    </contactnumbers>
    <emailaddresses>
      <emailaddress>johnson@example.com</emailaddress>
    </emailaddresses>
  </personinfo>  
  <organizationinfo>
    <namedetails>
      <organizationnamedetails>
        <organizationname>XYZ Corporation</organizationname>
        <otherinfo>c/o </otherinfo>
      </organizationnamedetails>
    </namedetails>
    <addressdetails>
      <thoroughfare>52 New Main St.</thoroughfare>
      <locality>
         <localityname>Carrboro</localityname>
         <postalcode>27510</postalcode>
      </locality>
      <administrativearea>NC</administrativearea>
      <country>USA</country>
    </addressdetails>
  </organizationinfo>
</authorinformation>

2.7.2.2 xNAL usage guidelines

DITA elements associated with xNAL elements

Example 1: Tagging personal information in DITA

Example 2: Tagging address information in DITA

Example 3: Tagging complex name and address information in DITA