9 Applying namespaces, elements, and attributes

xNAL offers a choice of four different namespaces as illustrated in Figure 15.

NOTE: Each of the namespaces illustrated above has its specific purpose and application. It is highly recommended to follow the purpose of the namespace and apply it accordingly.

NOTE

Each of the namespaces illustrated above has its specific purpose and application. It is highly recommended to follow the purpose of the namespace and apply it accordingly.

Normally, the choice of which of the namespaces to apply in a particular situation is made at the design time and hard-coded into the application later. Every design situation is different and has its own specific requirements. These guidelines do not recommend use of a namespace of higher complexity than necessary. For example, if xNAL is to be used to specify a name and surname of a citizen as part of other agency-specific information there is no reason to use xNAL namespace - xNL-basic namespace would be sufficient.

The following table provides some best practice recommendations for making a decision on which namespace to use:

Data combination	Recommended namespace
Basic person name (one level - no former or other names)	xNL-basic
Basic organisation name (one level - no former or other names)	xNL-basic
Basic organisation name including subdivisions (one level - no former or other names)	xNL-basic
A mix of basic person and organisation names as a batch	xNL
Complex person name, including former and other names	xNL
Complex organisation name, including former and other names	xNL
A name of unknown complexity	xNL
A mix of basic and complex names as a batch	xNL
A joint name of two or more persons	xNL
An address	xAL
A collection of addresses as a batch	xAL
An address with addressee name	xNAL
An address with more than one addressee	xNAL
A collection of related names and addresses	xNAL
A mix of unrelated names and addresses as a batch	xNAL
A name dependant on another name (for example a son of, or doing business as)	xNAL
Unrelated name and address data within the same exchange session	xNL and xAL separately

NOTE

The final choice of the appropriate namespace depends on the particular application and other specific requirements. These guidelines do not mandate which namespace should be chosen as long as the namespace is used correctly.

9.1 Elements and attributes

This section specifies detailed data quality requirements at the element/attribute level for each of the xNAL namespaces.

9.1.1 Elements and attributes for xNL - basic

Type and NameType attributes

Type and NameType attributes should be used consistently all through the namespace and should clarify the meaning of the element they belong to.

Type has an extensible list of valid values.

NameLine element

The NameLine element can be used for unparsed or supplementary data only.

Unparsed data should be marked with the appropriate value of the Type attribute (see 10.5, Common lists of values).

Additional information about the meaning of the element should be specified in the NameType attribute to assist the parser or the recipient with understanding the meaning of the data, as in the following example.

A plain English version of the example above can be specified as follows:

Mr John Johnson (unparsed full name of a person)

QC (unparsed, presumably suffix)

JJ (initials)

JJ are the initials of Mr John Johnson and are not required for xNL.

The recipient may ignore a NameLine element, with supplementary content, if the meaning of the content is not known or the recipient does not have an interest in that content.

NOTE

Programmers should remember:

xNAL is only XML with some pre-defined elements. You can always find an element to place your name and address data into.

However, the more you have broken up (parsed) your data so that it is distributed amongst many elements, the more powerful the applications are going to be that use that XML file.

For example:

If the name "Mr Andrew John Doe" is stored in one element called NameLine, you can only use that whole string as is.

If it was broken up into "Mr", "Andrew", "John", "Doe" ("Title", "FirstName", "MiddleName", "LastName" respectively), then there are many more options as to how that information is used; for example, searching on the last name only, extracting only male customers, combing these elements with a spouse's elements to more succinctly display their details, and so on.

For more detail on parsed versus unparsed data see Section 8.2, The parser's role in data quality.

ID attribute of PersonName and OrganisationName elements

The ID attribute provides an interoperable way of uniquely identifying an element as opposed to a person or organisation. The ID is not persistent, and it is up to the parties involved to locate the appropriate record. Also, the parties may agree on the persistence of the ID attribute for further data exchange. A sample application of this attribute is illustrated in Figure 16.

The ID is a GUID and may be generated for every exchange instance separately.

9.1.2 Elements and attributes for xNL

NameLine element

NOTE

The NameLine element should be used for unparsed data only—when it is impossible to say that name is of a certain type (such as person, organisation, or joint name).

Below is an example using the NameLine element.

PartyType attribute

The PartyType attribute of the NameDetails element provides additional information about the nature of the name, such as Club or Charity.

NameDetailsKey attribute

The NameDetailsKey attribute provides an interoperable way of uniquely identifying a NameDetails element. The value of the attribute is not persistent, and it is up to the parties involved to locate the appropriate element. Application of this element is similar to the application of the ID attribute of PersonName and OrganisationName elements from xNL-basic namespace. See Figure 16 for a sample application.

FormerName and KnownAs elements

It often happens that people or organisations change their names. If the name history should be represented in xNL form then FormerName elements should be used for all previous names.

NOTE

Use the KnownAs element if a person or organisation is known under more than one name.

Below is an example using the FormerName element.

ValidFrom and ValidTo attributes

These attributes specify the timeframe when a particular name was valid.

These attributes apply to FormerName and KnownAs elements for PersonName and OrganisationName.

It is assumed that the name details specified directly under PersonName or OrganisationName are current, unless the parties involved agreed otherwise.

JointNameConnector attribute of JointPersonName element

The JointNameConnector attribute of the JointPersonName element provides the logical connection between PersonNames included in the joint name. The value is most likely to be "and", but other values are also possible.

In the case where more than two names are being joined together, there is still only one connector. Applications should use commas to separate the names and the connector before the last name.

For example,

John, Ellen and Bruce Johnson

would transcribe into xNL as the following:

xNAL does not require merging identical surnames—it is up to the application to do so.

The XML example above can be restored to plain English as:

John Johnson, Ellen Johnson and Bruce Johnson

9.1.3 Elements and attributes for xAL

9.1.3.1 Type attribute

The Type attribute is used all across this namespace in a consistent manner, bearing the same meaning, unless specified otherwise.

This attribute refines the meaning of its parent element, for example specifying whether the element Name is official or unofficial, former name or abbreviation, and so on.

9.1.3.2 AddressDetails element

The AddressDetails element contains information about one particular address point. The address point can be represented at a varying scale—from a country to a particular premise. The AddressDetails element does not necessary specify the final destination to its finest details. The AddressDetails element may still be valid for the xNAL namespace if it has one or more direct child elements (such as Country or Locality) without specifying the final destination (for example the Premise). Applications, however, may restrict this rule if they require a particular level of address detail to comply with business rules.

AddressDetails is the primary element for exchange of address information.

9.1.3.3 AddressDetailsKey attribute

The AddressDetailsKey attribute provides an interoperable way of uniquely identifying an element of an address, not a complete address. The value of this attribute is not persistent, and it is up to the parties involved in the data exchange to locate the appropriate element. Also, the parties may agree on the persistence of the AddressDetailsKey attribute for further data exchange. For more information of cross-referencing within the xAL namespace, see Section 7.1, xAL referencing through the AddressDetailsKey attribute.

The value is of type GUID and can be generated for every exchange instance separately.

9.1.3.4 ComplementWith attribute

The ComplementWith attribute references another AddressDetails element through its AddressDetailsKey attribute. See Section 7.1, xAL referencing through the AddressDetailsKey attribute for more details about cross-referencing rules within xAL namespace.

9.1.3.5 ComplexNumberType type

ComplexNumberType is a class representing a number as a complex structure with some special properties. For example, street number, premise number, and postal code are supposed to be numbers, but they are not always numeric. The structure of this class is illustrated in Figure 17.

This structure is reused across the xAL namespace.

The core element is Number—which is just a name. The actual datatype of the Number element is xNLb:string (see Section 8.1.1, Strong data typing for more details). This element can contain any alphanumeric value within constraints of the xNLb:string datatype. The NumberPrefix and NumberSuffix elements are similar to the Number element, but they are used only for complex numbers containing more than one part. Normally, only one Number element is sufficient.

The following is a basic example of "111 Willis St" as a ComplexNumberType structure:

A more complex example can include NumberPrefix or NumberSuffix elements. For example, a business's

PO Box 324

would have the following xNAL equivalent

9.1.3.6 NameType type

NameType is a class representing a feature name as a complex structure with some special attributes. This structure is reused across the xAL namespace.

There is no core element in this structure. The core is a text node of the xNLb:string type, so that the actual element can have different names, but still belongs to the same class. The NameType structure is illustrated in Figure 18.

Generally in xAL, namespace elements named "Name" are of type NameType.

9.1.3.7 NumberRangeType type

The NumberRangeType type provides an option to specify a range of numbers, as in see Figure 19.

For example, for this address:

111-125 The Terrace

the xNAL equivalent is:

Normally, in the xAL namespace, elements named NumberRange are of the NumberRangeType type. The child elements "From" and "To" are both of the ComplexNumberType type and should contain values of the bottom and the top numbers of the range, respectively.

The default rule for this type is that all number ranges should be split into "From" and "To" values, unless otherwise explicitly specified.

The default presentation of number ranges for New Zealand addresses uses "-" as a separator, however, it is possible to specify other types of separators through the formatting attributes, as in the following example:

See Section 5.1, Address formatting attributes (helpful for overseas addresses) for more information about formatting attributes.

9.1.3.8 BuildingName element

BuildingName is a child element of element Premise. It provides a common name of the building, which is a premise in terms of xAL.

Building name is a redundant piece of information if the address is specified in full, including a street name and number. However, it is of a great importance because it is easier to remember a building name, rather than a range of numbers, as in the following example:

Ascent Technology

Level 4, Eagle Technology House

150-154 Willis St

Wellington

Building name is also helpful for delivery and pick-up, for example for couriers or taxis.

Building name should not be removed from this address if it was originally supplied as part of the address, unless it doesn't match the rest of the address. If the building name doesn't match the rest of the address it is up to the parser to determine whether the building name should be removed or corrected or if some other components of the address should be changed.

The following XML example illustrates an xAL equivalent of the address provided above.

9.1.3.9 PremiseDependencyType attribute

The PremiseDependencyType attribute belongs to the SubPremise element and indicates the type of dependency between premises, if the dependency type needs to be specified.

The value of this attribute is a connector between the sub-premise and the parent premise, with the value referring from the sub-premise to the parent. The following is an example of an address with a sub-premise:

Ground floor

Florists shop at the rear of Lambton Square

111-125 The Terrace

with an equivalent xAL form of this address:

It is recommended that Location element be used instead of PremiseDependencyType attribute, where possible.

9.1.3.10 DependentThoroughfareIndicator attribute

The DependentThoroughfareIndicator attribute belongs to DependentThoroughfare element and clarifies the relationship between the parent and dependant thoroughfares. For example:

123 Rata Dr (corner of Mathai Cr)

has the main thoroughfare with number (123 Rata Dr) which is sufficient to identify the place, so the information that the place is at the corner of Mathai Cr is supplementary. The following is an xNAL version of this address:

The same address without a number would require a dependant thoroughfare like this:

Corner of Rata Dr and Mathai Cr

An xNAL equivalent of this address would be very similar to the previous example, except for the street number:

9.1.3.11 AddressLine and AddressLines element

NOTE

These elements can be used for unparsed or supplementary data —see Section 10.5, Common lists of values) only, similar to NameLine for supplementary name data.

All unparsed data should be marked with the appropriate value of Type attribute (see Section 10.5, Common lists of values), otherwise it can be ignored by other applications if the nature of this supplementary data is not familiar.

The AddressLines element is a standalone part of an address and it can exist along with other parsed data (see Figure 20) or on its own. Use this element when the nature of the unparsed data is uncertain, for example if the application cannot determine if the data specifies locality or premise level of address; or if the address exists in a completely unparsed form as line 1, line 2, line 3, and so on.

The following is an example of a completely unparsed address:

The AddressLines element can coexist with other elements with parsed data. In this example we assume that the application knew that the locality name was Wellington, but could not parse the rest of the address, so the remaining data resides under AddressLines.

The AddressLine element can be used as part of other parsed elements to provide unparsed or supplementary data. For example:

where AddressLine (in blue) has complementary data to help locate a small town. This data can be ignored by the recipient if not understood or not needed. However, the following example should be parsed first before being processed, because the attribute Type indicates that AddressLine element contains significant unparsed data.

9.1.3.12 Identifier and Identifiers elements

The Identifier element can be placed under top-level address elements or separately inside the Identifiers element.

An Identifier element provides a specific unique identifier from a particular identifier system. The attribute Type specifies the type of the identifier system (see Section 10.5, Common lists of values for a list of acceptable values). There is no particular format for the identifier except that it should be within the limits of the data type specified in the schema.

The place of the Identifier element determines what part of the address the identifier relates to.

Scenario:

Let's say that Land and Information New Zealand (LINZ) and New Zealand Post (NZ Post) were to provide identifier systems for New Zealand locations and addresses. The following is a fictitious example of sending an address with identifiers:

The first LINZ identifier with value "aaa" identifies the administrative area only.

The second LINZ identifier with value "bbb" identifies the locality only.

The NZ Post identifier with value "zzz" identifies the actual delivery point as a combination of the administrative area, locality, and thoroughfare name and number because it resides at the top level and relates to the address as a whole.

Assuming that the recipient of this address detail has access to those identifier systems the same address could be provided as:

Depending on the identifier system, you may not need to specify the higher-level address elements if you provide an identifier for a lower-level element; for example, there is no need to specify an administrative-area identifier if the locality identifier already refers to a particular place of finer granularity. Thus the same address can be simplified to:

Using a (fictitious) NZ Post identifier for the delivery point, the address can be simplified even further:

Check these guidelines on the use of the particular identifier system for more details

(see Sections 8.1.3, Identifiers and Appendix C New Zealand wide identifiers ).

9.1.3.13 Country element

Country element is of the broadest granularity and is not required for New Zealand addresses.

The default rule is that if no Country is specified, it is a New Zealand address, unless the parties have agreed otherwise.

To specify a country code, use an identifier element according to one of the encoding schemes such as ISO 3166.

9.1.3.14 AdministrativeArea element

The AdministrativeArea element is used to specify an area that corresponds to an official administration segment of some type, such as a state, province, electorate, or county council. This administrative area does not necessarily form part of the address for delivery purposes, but it may be critical for address identification or other specific purposes related to that administrative division system. There is no size limit for the administrative area that can also be nested through SubAdministrativeArea element.

New Zealand examples of administrative areas are Southland, Central Otago, Belmont Electorate, Wellington CBD, and Lower Hutt.

The AdministrativeArea element may not be required if there are identifiers that can help identify the locality or another address element of a finer granularity.

9.1.3.15 Locality element

Generally, a locality in New Zealand can be a city (such as Auckland), town (such as Castle Point) or suburb (such as Albany). Some smaller areas such as army camps, hospitals, or airports can be represented as localities, but only if they take up significant territories and have a number of premises there.

Localities can be nested from a bigger locality to a smaller one, for example:

Emergency Department

Main Building

Wellington Hospital

Newtown

Wellington

may have the xNAL equivalent:

9.1.3.16 Thoroughfare element

The Thoroughfare element is an access road to the address, for example street, road, state highway, or square. Generally, a thoroughfare has a name and number that refer to a particular site or premise.

Thoroughfare elements can be nested through DependentThoroughfare element; for example, a farmer's house near a small place called Putara may have a private driveway that is not marked on any map, so providing another reference point is necessary:

3 McClay's Dr

Putara Rd

Tararua

This address has the xNAL equivalent:

A thoroughfare name should not contain abbreviations in its parsed form. In the example above (and in all other examples involving thoroughfare names), all abbreviations are resolved, for example Dr becomes Drive, Rd becomes Road, and so on.

9.1.3.17 Premise element

The Premise element provides information about a site or a building. Normally, a premise can be addressed through its name (for featured or well-known buildings) or a thoroughfare number.

A premise can be further refined to a finer granularity through a SubPremise element as in the following example:

Gift Shop

Plaza Mall

217 Main St

Upper Hutt

has the xNAL equivalent:

Premise versus locality

Occasionally it is difficult to say whether an address element is a premise or a locality, especially for bigger sites such as hospitals or universities.

The Locality element is the preferred option for cases where internal addressing system must be used, such as a street name or lane number. The Premise element does not allow a Thoroughfare element as its child, so the Locality element should be used instead.

If it is agreed that only one level of sub-premise can be used, Location may have to be used in order to provide sufficient structure for multiple levels of sub-premise.

9.1.3.18 Geospatial element

The Geospatial element is a container for any geospatial data (an address which has "location intelligence" built in) that relates to the address. If an application is required to analyse the "where" or how these addresses relate (spatially) then a geographical schema needs to be employed. There is a namespace restriction for the descendants of this element, which means that only elements from that particular namespace can be used as the descendants. Consult the xAL schema to find out the exact namespace identifier (see Section 5, Address (xAL) overview).

Note: The following example uses fictitious elements for the namespace associated with the Geospatial element

The scope of the Geospatial element is for the element of the finest granularity; for example, building number 217 on The Terrace in Wellington. The exact geospatial features of the building described by the GML (Geography Markup Language, refer http://www.opengis.org/specs/) elements should be specified within the Geospatial element.

It is possible to describe multiple features or use different geospatial schemas within the same Geospatial element.

Geospatial information can be provided for any level of address details, not necessarily for a building—it can be a neighbourhood, a town, or even a Country. For example, the following presumes that the GML elements describe the boundaries of Putara:

xNAL does not prescribe how the content of the Geospatial element should be used or what sort of content it should be. It is the responsibility of the parties to reach an agreement.

9.1.4 Elements and attributes for xNAL

9.1.4.1 PostalLabel element

The PostalLabel element is used for providing name and address information for posting purposes. This element provides an option of addressing an anonymous person or organisation through a designation. Consider the following example:

The Rural Party Leader

Hon Mr Jack Hog

The Parliament

Neither xNL nor xAL provide any means to specify the designation of the Hon Mr Hog.

The following xNAL illustrates a solution:

It is often the case that the name of the recipient is not known to the sender—only the designation. The same example without the name would be as follows:

9.1.4.1 ID attribute

The ID attribute of elements Record and PostalLabel provides unique identification of these elements. The value of the ID attribute is not persistent and can be generated every time as required.

Neither Record nor PostalLabel elements are referenced from within the xNAL namespaces through the ID attribute, but they may be referenced from other namespaces.

It is the responsibility of the parties to agree on how they use the ID attribute and how they locate the referenced elements. See Section 7, Relational models (referencing) for more details on use of identifiers in xNAL.

[ Previous | Next ]