Using XML Namespaces

In this post we will review why the namespace is so important in an XML document. Also we’ll discuss the common names for a namespace.

xml-logo

 

What is a Namespace?

XML namespace is a unique identifier that holds information about the creator of the document, in other words it is like a signature. This identifier could avoid problems when we want to reuse an XML that somebody else wrote. Let’s take a look at the following example:

This is an XML of a reservation, very simple, but let’s suppose that we have to merge the reservation XML with the room service XML:

At the beginning it looks fine, but hold on, take a closer look. We have a collision in 6 and 12 lines, both contain the same element with a different content. The same happens with the element in lines 7 and 13, but in this case they have the same content.

 

Avoiding Collisions in Namespaces

To avoid these collisions we have to identify the XML fragments using a namespace.

As you can see now the elements with conflicts have different names and they are using a prefix. Notice that the prefix is declared in the root node of the XML fragment.

The correct way to name your namespaces is first using the key word xmlns which means that a namespace is declared.

Then declare a prefix to refer the namespace in the elements

And at the end declare an URI to identify your XML fragments in a document, an URI means Uniform Resource Identifier and could be any string of characters that are considered unique, for example:

These three URI’s are a fully qualified name for a namespace. According to IETF an URI is a case sensitive sequence of characters from a very limited set: the letters of
the basic Latin alphabet, digits, and a few special characters.

 

Best Practices to Name Your Namespaces

The best practices state that your namespaces should provide information about the owner of the XML, the most frequently used names are:

  1. A unique name to identify your XML, this is not so common in the real world but is useful for tests, like ORDERS_XML.
  2. The name of an organization or product, like Sunset-Hotels.
  3. The domain name of an organization or company, this is the most widely used name, it’s simple and very descriptive, like com.ibm.xml, http://www.opentravel.org/OTA/2003/05/common

The last kind of URI is usually the best because you can describe a component in a hierarchical order, lets go back to the example http://marcotello.com/hotels/reservation as you can see here that reservation belongs to hotels and hotels belong to the domain or the organization, and this an easy way to have an order of the elements that you are representing.

The prefix that refers to your namespace in the document could be anything you like, some parsers don’t allow special characters so the best way is just to choose 3 letters like res. The keywords xmlns and xml are not allowed as prefixes.

A prefix is linked to the namespace with the namespace binding xmlns:prefix=”URI” like in the example xmlns:res=”http://marcotello.com/hotel/reservation” res is linked to http://marcotello.com/hotel/reservation namespace and you can use the prefix in your elements to distinguish as part of it.

Could be read like this:

I’m going to list all the best practices for the DeveloperWorks article Plan to use XML namespaces written by the XML expert David Marston, which in my opinion is the most complete guide of namespaces best practices:

Planning your namespaces

  • Establish logical and consistent prefix names to boost developer productivity.
  • Use prefixes everywhere or at least use them on all items except those that are the real content being delivered to the end user.
  • Apply namespaces to your own vocabulary, even when there is just one.
  • Treat namespaces as a way to separate or isolate terms that may otherwise seem similar.
  • When designing two vocabularies that have some elements in common, choose one namespace (possibly separate from the original two) to hold the common items.
  • Use HTTP URLs for your URIs, without fragment identifiers.
  • Coordinate URI naming under your domain name just as you do for names of machines on your network and your Web URLs.
  • Change the namespace URI for every substantive change to the vocabulary, including the addition of new elements forming a strict superset of the old vocabulary.

Usage inside XML documents

  • If possible, use one prefix for one namespace throughout all XML documents in a system.
  • Declare namespaces explicitly within each document, reducing assumptions and dependencies.
  • Make all namespace declarations up in the start tag of the document element if at all possible.
  • For W3C-defined elements and attributes, use the prefixes that the W3C uses.
  • Use the xml:lang attribute to declare that the content of the element is in a particular natural language.

Documentation and conversational usage

  • Refer to a “namespace declaration” as distinct from an “attribute” when discussing entries in a start tag.
  • Avoid the term “namespace name” or only use it in a context where it’s clear what you mean.
  • Use the domain names example.com, example.net, or example.org for examples in your documentation.

Following some of these best practices to merge our XML documents, we’ll get something like this:

As you can see namespaces are so important in XML documents because they can avoid collisions between elements with the same name, and also make it possible to catalog information across the enterprise, so next time you have to build an XML consider including a namespace in your root node.

 

Resources:

Leave a reply:

Your email address will not be published.

Copyright © 2016 Marco Tello.