Namespaces in XML 1.1

W3C Candidate Recommendation 18 December 2002

This version:
Latest version:
Previous version:
Tim Bray, Textuality <tbray@textuality.com>
Dave Hollander, Contivo, Inc. <dmh@contivo.com>
Andrew Layman, Microsoft <andrewl@microsoft.com>
Richard Tobin, University of Edinburgh and Markup Technology Ltd <richard@cogsci.ed.ac.uk>

This document is also available in these non-normative formats: XML.


XML namespaces provide a simple method for qualifying element and attribute names used in Extensible Markup Language documents by associating them with namespaces identified by IRI references.

Status of this Document

This is the draft dated $Date: 2002/12/18 15:58:32 $

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

This specification is being put forth as a W3C Candidate Recommendation of Namespaces in XML 1.1. W3C publishes a technical report as a Candidate Recommendation to indicate that the document is believed to be stable, and to encourage implementation by the developer community. Candidate Recommendation status is described in section 5.2.3 of the Process Document.

The XML Core Working Group (part of the XML Activity, see summary) expects to request that the Director advance this specification to Proposed Recommendation after the XML Core Working Group documents at least two interoperable implementations. The two implementations must be produced by different organizations.

The final version of this specification will refer to terms and productions from the 1.1 revision of the XML specification. Since that specification does not yet exist in a suitable form, in this draft they are links to the 1.0 specification where the difference is unimportant, or links to placeholders within this draft.

There is a requirements document for this revision [Requirements].

The current implementation report includes implementation feedback we have received to date.

Documentation of intellectual property possibly relevant to this recommendation may be found at the Working Group's public IPR disclosure page.

We explicitly invite comments on this draft. The Candidate Recommendation review period ends at 2359 UTC on 14 February 2003. Comments should be sent to xml-names-editor@w3.org. This is the preferred method of providing feedback. Public comments and their responses can be accessed at http://lists.w3.org/Archives/Public/xml-names-editor/.

Publication as a Candidate Recommendation does not imply endorsement by the W3C membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite a W3C Candidate Recommendation as anything other than a "work in progress." A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.

Table of Contents

1 Motivation and Summary
    1.1 A Note on Notation and Usage
2 XML Namespaces
    2.1 Basic Concepts
    2.2 Use of IRIs as Namespace Names
    2.3 Comparing IRI References
3 Declaring Namespaces
4 Qualified Names
5 Using Qualified Names
6 Applying Namespaces to Elements and Attributes
    6.1 Namespace Scoping
    6.2 Namespace Defaulting
    6.3 Uniqueness of Attributes
7 Conformance of Documents
8 Conformance of Processors
9 Internationalized Resource Identifiers (IRIs)
10 XML 1.1 Productions


A References
B The Internal Structure of XML Namespaces (Non-Normative)
C Changes since version 1.0 (Non-Normative)
D Acknowledgements (Non-Normative)

1 Motivation and Summary

We envision applications of Extensible Markup Language (XML) where a single XML document may contain elements and attributes (here referred to as a "markup vocabulary") that are defined for and used by multiple software modules. One motivation for this is modularity: if such a markup vocabulary exists which is well-understood and for which there is useful software available, it is better to re-use this markup rather than re-invent it.

Such documents, containing multiple markup vocabularies, pose problems of recognition and collision. Software modules need to be able to recognize the elements and attributes which they are designed to process, even in the face of "collisions" occurring when markup intended for some other software package uses the same element name or attribute name.

These considerations require that document constructs should have have names constructed so as to avoid clashes between names from different markup vocabularies. This specification describes a mechanism, XML namespaces, which accomplishes this by assigning expanded names to elements and attributes.

1.1 A Note on Notation and Usage

Note that many of the nonterminals in the productions in this specification are defined not here but in the XML specification [XML]. When nonterminals defined here have the same names as nonterminals defined in the XML specification, the productions here in all cases match a subset of the strings matched by the corresponding ones there.

In this document's productions, the NSC is a "Namespace Constraint", one of the rules that documents conforming to this specification must follow.

Note that all Internet domain names used in examples, with the exception of w3.org, are selected at random and should not be taken as having any import.

2 XML Namespaces

2.1 Basic Concepts

[Definition: An XML namespace is identified by an IRI reference; element and attribute names may be placed in an XML namespace using the mechanisms described in this specification. ]

[Definition: An expanded name is a pair consisting of a namespace name and a local name. ] [Definition: For a name in a namespace, the namespace name is the IRI identifying the namespace. For a name that is not in a namespace, the namespace name is null. ] [Definition: The local name is the name itself. ] It is this combination of the universally managed IRI namespace with the vocabulary's local names that is effective in avoiding name clashes.

IRI references can contain characters not allowed in names, and are often inconveniently long, so expanded names are not used directly to name elements and attributes in XML documents. Instead qualified names are used. [Definition: A qualified name is a name subject to namespace interpretation. ] In documents conforming to this specification, element and attribute names appear as qualified names. Syntactically, they are either prefixed names or unprefixed names. An attribute-based declaration syntax is provided to bind prefixes to namespace names and to bind a default namespace that applies to unprefixed element names; these declarations are scoped by the elements on which they appear so that different bindings may apply in different parts of a document. Processors conforming to this specification must recognize and act on these declarations and prefixes.

2.2 Use of IRIs as Namespace Names

The empty string, though it is a legal IRI reference, cannot be used as a namespace name.

The use of relative IRI references, including same-document references, in namespace declarations is deprecated. Future W3C specifications will define no interpretation for them.

2.3 Comparing IRI References

IRI references identifying namespaces are compared when determining whether a name belongs to a given namespace, and whether two names belong to the same namespace. [Definition: The two IRIs are treated as strings, and they are identical if and only if the strings are identical, that is, if they are the same sequence of characters. ] The comparison is case-sensitive, and no %-escaping is done or undone.

A consequence of this is that IRI references which are not identical in this sense may resolve to the same resource. Examples include IRI references which differ only in case or %-escaping, or which are in external entities which have different base URIs (but note that relative IRIs are deprecated as namespace names).

In a namespace declaration, the IRI reference is the normalized value of the attribute, so replacement of XML character and entity references has already been done before any comparison.


The IRI references below are all different for the purposes of identifying namespaces, since they differ in case:

  • http://www.example.org/wine

  • http://www.Example.org/wine

  • http://www.example.org/Wine

The IRI references below are also all different for the purposes of identifying namespaces:

  • http://www.example.org/rosé

  • http://www.example.org/ros%c3%a9

  • http://www.example.org/ros%c3%A9

  • http://www.example.org/ros%C3%a9

  • http://www.example.org/ros%C3%A9

As are these:

  • http://www.example.org/~wilbur

  • http://www.example.org/%7ewilbur

  • http://www.example.org/%7Ewilbur

If the entity eacute has been defined to be é, the start tags below all contain namespace declarations binding the prefix p to the same IRI reference, http://example.org/rosé.

  • <p:foo xmlns:p="http://example.org/rosé">

  • <p:foo xmlns:p="http://example.org/ros&#xe9;">

  • <p:foo xmlns:p="http://example.org/ros&#xE9;">

  • <p:foo xmlns:p="http://example.org/ros&#233;">

  • <p:foo xmlns:p="http://example.org/ros&eacute;">

3 Declaring Namespaces

[Definition: A namespace (or more precisely, a namespace binding) is declared using a family of reserved attributes. Such an attribute's name must either be xmlns or begin xmlns:. These attributes, like any other XML attributes, may be provided directly or by default. ]

Attribute Names for Namespace Declaration
[1]   NSAttName   ::=   PrefixedAttName
| DefaultAttName
[2]   PrefixedAttName   ::=   'xmlns:' NCName[NSC: Reserved Prefixes and Namespace Names]
[3]   DefaultAttName   ::=   'xmlns'
[4]   NCName   ::=   NCNameStartChar NCNameChar*/* An XML Name, minus the ":" */
[5]   NCNameChar   ::=   NameChar - ':'
[5a]   NCNameStartChar   ::=   NameStartChar - ':'

The attribute's normalized value must be either an IRI reference — the namespace name identifying the namespace — or an empty string. The namespace name, to serve its intended purpose, should have the characteristics of uniqueness and persistence. It is not a goal that it be directly usable for retrieval of a schema (if any exists). An example of a syntax that is designed with these goals in mind is that for Uniform Resource Names [RFC2141]. However, it should be noted that ordinary URLs can be managed in such a way as to achieve these same goals.

[Definition: If the attribute name matches PrefixedAttName, then the NCName gives the namespace prefix, used to associate element and attribute names with the namespace name in the attribute value in the scope of the element to which the declaration is attached.] The attribute value may be an empty string.

[Definition: If the attribute name matches DefaultAttName, then the namespace name in the attribute value is that of the default namespace in the scope of the element to which the declaration is attached.] The attribute value may be an empty string. Default namespaces and overriding of declarations are discussed in 6 Applying Namespaces to Elements and Attributes.

An example namespace declaration, which associates the namespace prefix edi with the namespace name http://ecommerce.org/schema:

<x xmlns:edi='http://ecommerce.org/schema'>
  <!-- the "edi" prefix is bound to http://ecommerce.org/schema
       for the "x" element and contents -->

Namespace constraint: Reserved Prefixes and Namespace Names

The prefix xml is by definition bound to the namespace name http://www.w3.org/XML/1998/namespace. It may, but need not, be declared, and must not be bound to any other namespace name. No other prefix may be bound to this namespace name.

The prefix xmlns is used only to declare namespace bindings and is by definition bound to the namespace name http://www.w3.org/2000/xmlns/. It must not be declared. No other prefix may be bound to this namespace name.

All other prefixes beginning with the three-letter sequence x, m, l, in any case combination, are reserved. This means that:

  • users should not use them except as defined by later specifications

  • processors must not treat them as fatal errors.

Though they are not themselves reserved, it is inadvisable to use prefixed names whose LocalPart begins with the letters x, m, l, in any case combination, as these names would be reserved if used without a prefix.

4 Qualified Names

In XML documents conforming to this specification, some names (constructs corresponding to the nonterminal Name) must be given as qualified names, defined as follows:

Qualified Name
[6]   QName   ::=   PrefixedName
| UnprefixedName
[6a]   PrefixedName   ::=    Prefix ':' LocalPart
[6b]   UnprefixedName   ::=    LocalPart
[7]   Prefix   ::=   NCName
[8]   LocalPart   ::=   NCName

The Prefix provides the namespace prefix part of the qualified name, and must be associated with a namespace IRI reference in a namespace declaration. [Definition: The LocalPart provides the local part of the qualified name.]

Note that the prefix functions only as a placeholder for a namespace name. Applications should use the namespace name, not the prefix, in constructing names whose scope extends beyond the containing document.

5 Using Qualified Names

In XML documents conforming to this specification, element names are given as qualified names, as follows:

Element Names
[9]   STag   ::=   '<' QName (S Attribute)* S? '>' [NSC: Prefix Declared]
[10]   ETag   ::=   '</' QName S? '>'[NSC: Prefix Declared]
[11]   EmptyElemTag   ::=   '<' QName (S Attribute)* S? '/>'[NSC: Prefix Declared]

An example of a qualified name serving as an element name:

  <!-- the 'price' element's namespace is http://ecommerce.org/schema -->
  <edi:price xmlns:edi='http://ecommerce.org/schema' units='Euro'>32.18</edi:price>

Attributes are either namespace declarations or their names are given as qualified names:

[12]   Attribute   ::=   NSAttName Eq AttValue
| QName Eq AttValue[NSC: Prefix Declared]

An example of a qualified name serving as an attribute name:

<x xmlns:edi='http://ecommerce.org/schema'>
  <!-- the 'taxClass' attribute's namespace is http://ecommerce.org/schema -->
  <lineItem edi:taxClass="exempt">Baby food</lineItem>

Namespace constraint: Prefix Declared

The namespace prefix, unless it is xml or xmlns, must have been declared in a namespace declaration attribute in either the start-tag of the element where the prefix is used or in an ancestor element (i.e. an element in whose content the prefixed markup occurs). Furthermore, the attribute value in the innermost such declaration must not be an empty string.

This constraint may lead to operational difficulties in the case where the namespace declaration attribute is provided, not directly in the XML document entity, but via a default attribute declared in an external entity. Such declarations may not be read by software which is based on a non-validating XML processor. Many XML applications, presumably including namespace-sensitive ones, fail to require validating processors. If correct operation with such applications is required, namespace declarations must be provided either directly or via default attributes declared in the internal subset of the DTD.

Element names and attribute names are also given as qualified names when they appear in declarations in the DTD:

Qualified Names in Declarations
[13]   doctypedecl   ::=   '<!DOCTYPE' S QName (S ExternalID)? S? ('[' (markupdecl | PEReference | S)* ']' S?)? '>'
[14]   elementdecl   ::=   '<!ELEMENT' S QName S contentspec S? '>'
[15]   cp   ::=   (QName | choice | seq) ('?' | '*' | '+')?
[16]   Mixed   ::=   '(' S? '#PCDATA' (S? '|' S? QName)* S? ')*'
| '(' S? '#PCDATA' S? ')'
[17]   AttlistDecl   ::=   '<!ATTLIST' S QName AttDef* S? '>'
[18]   AttDef   ::=   S (QName | NSAttName) S AttType S DefaultDecl

Note that DTD-based validation is not namespace-aware; no mechanism is provided for binding or defaulting namespaces within a DTD, and element and attribute names in declarations are matched literally against names in the instance. To validate a document that uses namespaces against a DTD, the same prefixes must be used in the DTD as in the instance.

6 Applying Namespaces to Elements and Attributes

6.1 Namespace Scoping

The scope of a namespace declaration declaring a prefix extends from the beginning of the start-tag in which it appears to the end of the corresponding end-tag, excluding the scope of any inner declarations with the same NSAttName part. In the case of an empty tag, the scope is the tag itself.

Such a namespace declaration applies to to all element and attribute names within its scope whose prefix matches that specified in the declaration.

The expanded name corresponding to a prefixed element or attribute name has the IRI to which the prefix is bound as its namespace name, and the local part as its local name.

<?xml version="1.1"?>

<html:html xmlns:html='http://www.w3.org/1999/xhtml'>

  <html:body><html:p>Moved to 
    <html:a href='http://frob.com'>here.</html:a></html:p></html:body>

Multiple namespace prefixes can be declared as attributes of a single element, as shown in this example:

<?xml version="1.1"?>
<!-- both namespace prefixes are available throughout -->
<bk:book xmlns:bk='urn:loc.gov:books'
    <bk:title>Cheaper by the Dozen</bk:title>

The attribute value in a namespace declaration for a prefix may be empty. This has the effect, within the scope of the declaration, of removing any association of the prefix with a namespace name. Further declarations may re-declare the prefix again:

<?xml version="1.1"?>
<x xmlns:n1="http://www.w3.org">
    <n1:a/>               <!-- legal; the prefix n1 is bound to http://www.w3.org -->
    <x xmlns:n1="">
        <n1:a/>           <!-- illegal; the prefix n1 is not bound here -->
	<x xmlns:n1="http://www.w3.org">
            <n1:a/>       <!-- legal; the prefix n1 is bound again -->

6.2 Namespace Defaulting

The scope of a default namespace declaration extends from the beginning of the start-tag in which it appears to the end of the corresponding end-tag, excluding the scope of any inner default namespace declarations. In the case of an empty tag, the scope is the tag itself.

A default namespace declaration applies to to all unprefixed element names within its scope. Default namespace declarations do not apply directly to attribute names; the interpretation of unprefixed attributes is determined by the element on which they appear.

If there is a default namespace declaration in scope, the expanded name corresponding to an unprefixed element name has the IRI of the default namespace as its namespace name. If there is no default namespace declaration in scope, the namespace name is null. The namespace name for an unprefixed attribute name is always null. In all cases, the local name is local part (which is of course the same as the unprefixed name itself).

<?xml version="1.1"?>
<!-- elements are in the HTML namespace, in this case by default -->
<html xmlns='http://www.w3.org/1999/xhtml'>
  <body><p>Moved to 
    <a href='http://frob.com'>here</a>.</p></body>
<?xml version="1.1"?>
<!-- unprefixed element types are from "books" -->
<book xmlns='urn:loc.gov:books'
    <title>Cheaper by the Dozen</title>

A larger example of namespace scoping:

<?xml version="1.1"?>
<!-- initially, the default namespace is "books" -->
<book xmlns='urn:loc.gov:books'
    <title>Cheaper by the Dozen</title>
      <!-- make HTML the default namespace for some commentary -->
      <p xmlns='http://www.w3.org/1999/xhtml'>
          This is a <i>funny</i> book!

The default namespace can be set to the empty string. This has the same effect, within the scope of the declaration, of there being no default namespace.

<?xml version='1.1'?>
  <!-- the default namespace inside tables is that of HTML -->
  <table xmlns='http://www.w3.org/1999/xhtml'>
     <!-- no default namespace inside table cells -->
     <td><brandName xmlns="">Huntsman</brandName></td>
     <td><origin xmlns="">Bath, UK</origin></td>
       <details xmlns=""><class>Bitter</class><hop>Fuggles</hop>
         <pro>Wonderful hop, light alcohol, good summer beer</pro>
         <con>Fragile; excessive variance pub to pub</con>

6.3 Uniqueness of Attributes

In XML documents conforming to this specification, no tag may contain two attributes which:

  1. have identical names, or

  2. have qualified names with the same local part and with prefixes which have been bound to namespace names that are identical.

This constraint is equivalent to requiring that no element have two attributes with the same expanded name.

For example, each of the bad start-tags is illegal in the following:

<!-- http://www.w3.org is bound to n1 and n2 -->
<x xmlns:n1="http://www.w3.org" 
   xmlns:n2="http://www.w3.org" >
  <bad a="1"     a="2" />
  <bad n1:a="1"  n2:a="2" />

However, each of the following is legal, the second because the default namespace does not apply to attribute names:

<!-- http://www.w3.org is bound to n1 and is the default -->
<x xmlns:n1="http://www.w3.org" 
   xmlns="http://www.w3.org" >
  <good a="1"     b="2" />
  <good a="1"     n1:a="2" />

7 Conformance of Documents

This specification applies to XML 1.1 documents. To conform to this specification, a document must be well-formed according to the XML 1.1 specification.

In XML documents which conform to this specification, element and attribute names must match the production for QName and must satisfy the "Namespace Constraints". All other tokens in the document which are required, for XML 1.1 well-formedness, to match the XML production for Name, must match this specification's production for NCName.

[Definition: A document is namespace-well-formed if it conforms to this specification. ]

It follows that in a namespace-well-formed document:

In addition, a namespace-well-formed document may also be namespace-valid.

[Definition: A namespace-well-formed document is namespace-valid if it is valid according to the XML 1.1 specification, and all tokens other than element and attribute names which are required, for XML 1.1 validity, to match the XML production for Name, match this specification's production for NCName. ]

It follows that in a namespace-valid document:

8 Conformance of Processors

To conform to this specification, a processor must report violations of namespace well-formedness, with the exception that it it not required to check that namespace names are legal IRIs.

[Definition: A validating XML processor that conforms to this specification is namespace-validating if in addition it reports violations of namespace validity. ]

9 Internationalized Resource Identifiers (IRIs)

Work is currently in progress to produce an RFC defining Internationalized Resource Identifiers (IRIs). Since this work is not yet complete, in this section we give a syntactic definition of IRIs for the purposes of this specification. We expect to issue an erratum replacing this section with a reference to the RFC when it is published. Users defining namespaces are advised to restrict namespace names to URIs until software supporting IRIs is in common use.

For a more general definition and discussion of IRIs see [IRI draft] (work in progress).

URI references are restricted to a subset of the ASCII characters; IRI references allow some of the disallowed ASCII characters as well as most Unicode characters from #xA0 onwards.

[Definition: The additional characters allowed in IRIs are: ]

[Definition: An IRI reference is a string that can be converted to a URI reference by escaping all additional characters as follows: ]

  1. Each additional character is converted to UTF-8 [Unicode 3.2] as one or more bytes.

  2. The resulting bytes are escaped with the URI escaping mechanism (that is, converted to %HH, where HH is the hexadecimal notation of the byte value).

  3. The original character is replaced by the resulting character sequence.

10 XML 1.1 Productions

This section will not be present in the final version of this specification. It contains productions that will appear in the XML 1.1 specification and are different from those in XML 1.0.

XML 1.1 Productions
[19]   Name   ::=   NameStartChar NameChar*
[20]   NameChar   ::=   /* To be defined in XML 1.1 */
[21]   NameStartChar   ::=   /* To be defined in XML 1.1 */

A References

IRI draft
Internationalized Resource Identifiers (IRIs). Available at http://www.w3.org/International/iri-edit/draft-duerst-iri-02.txt
1.0 Errata
Namespaces in XML Errata. Available at http://www.w3.org/XML/xml-names-19990114-errata
Namespaces in XML 1.1 Requirements, ed. Jonathan Marsh. March 2002. Available at http://www.w3.org/TR/2002/WD-xml-names11-req-20020403/
IETF (Internet Engineering Task Force) RFC 2141: URN Syntax, ed. R. Moats. May 1997. Available at ftp://ftp.ietf.org/rfc/rfc2141.txt
IETF (Internet Engineering Task Force) RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax, eds. T. Berners-Lee, R. Fielding, L. Masinter. August 1998. Available at ftp://ftp.ietf.org/rfc/rfc2396.txt
IETF (Internet Engineering Task Force) RFC 2732: Format for Literal IPv6 Addresses in URL's, eds. R. Hinden, B. Carpenter, L. Masinter. December 1999. Available at http://www.ietf.org/rfc/rfc2732.txt
Unicode 3.2
The Unicode Consortium The Unicode Standard, Version 3.2.0 is defined by The Unicode Standard, Version 3.0 (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5), as amended by the Unicode Standard Annex #27: Unicode 3.1 (see http://www.unicode.org/reports/tr27) and by the Unicode Standard Annex #28: Unicode 3.2 ( http://www.unicode.org/reports/tr28).
Extensible Markup Language (XML) 1.0 (Second Edition), eds. Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, and Eve Maler. 6 October 2000. Available at http://www.w3.org/TR/2000/REC-xml-20001006.
XML 1.1 CR draft
Extensible Markup Language (XML) 1.1, ed. John Cowan 15 October 2002. Available at http://www.w3.org/TR/2002/CR-xml11-20021015/.

B The Internal Structure of XML Namespaces (Non-Normative)

This appendix has been deleted.

C Changes since version 1.0 (Non-Normative)

This version incorporates the errata to version 1.0 as of 6 December 2002 [1.0 Errata]. There are two further substantive changes:

There are several editorial changes, including a number of terminology changes and additions intended to produce greater consistency. The non-normative appendix "The Internal Structure of XML Namespaces" has been removed.

D Acknowledgements (Non-Normative)

This work reflects input from a very large number of people, including especially the members of the World Wide Web Consortium XML Working Group and Special Interest Group and the participants in the W3C Metadata Activity. The contributions of Charles Frankston of Microsoft were particularly valuable.