0
# Namespace Support
1

2
Comprehensive XML Namespace support with namespace-aware methods, prefix handling, namespace URI resolution, and full compliance with XML Namespaces specification.
3

4
## Capabilities
5

6
### Namespace-Aware Element Methods
7

8
Element interface extensions that provide full namespace support for creating, accessing, and manipulating namespaced elements and attributes.
9

10
```javascript { .api }
11
/**
12
 * Namespace-aware methods on Element interface
13
 */
14
interface Element extends Node {
15
  /**
16
   * Gets attribute value by namespace URI and local name
17
   * @param namespaceURI The namespace URI or null for no namespace
18
   * @param localName The local name of the attribute
19
   * @returns Attribute value or empty string if not found
20
   */
21
  getAttributeNS(namespaceURI: string | null, localName: string): string;
22
  
23
  /**
24
   * Sets attribute value by namespace URI and qualified name
25
   * @param namespaceURI The namespace URI or null for no namespace
26
   * @param qualifiedName The qualified name (prefix:localName or localName)
27
   * @param value The attribute value to set
28
   */
29
  setAttributeNS(namespaceURI: string | null, qualifiedName: string, value: string): void;
30
  
31
  /**
32
   * Removes attribute by namespace URI and local name
33
   * @param namespaceURI The namespace URI or null for no namespace
34
   * @param localName The local name of the attribute
35
   */
36
  removeAttributeNS(namespaceURI: string | null, localName: string): void;
37
  
38
  /**
39
   * Gets attribute node by namespace URI and local name
40
   * @param namespaceURI The namespace URI or null for no namespace
41
   * @param localName The local name of the attribute
42
   * @returns Attr node or null if not found
43
   */
44
  getAttributeNodeNS(namespaceURI: string | null, localName: string): Attr | null;
45
  
46
  /**
47
   * Sets attribute node with namespace support
48
   * @param newAttr The Attr node to set
49
   * @returns Previous Attr node or null
50
   */
51
  setAttributeNodeNS(newAttr: Attr): Attr | null;
52
  
53
  /**
54
   * Gets elements by namespace URI and local name
55
   * @param namespaceURI The namespace URI or "*" for any namespace
56
   * @param localName The local name or "*" for any name
57
   * @returns NodeList of matching elements
58
   */
59
  getElementsByTagNameNS(namespaceURI: string | null, localName: string): NodeList;
60
  
61
  /**
62
   * Tests if attribute exists by namespace URI and local name
63
   * @param namespaceURI The namespace URI or null for no namespace
64
   * @param localName The local name of the attribute
65
   * @returns true if attribute exists
66
   */
67
  hasAttributeNS(namespaceURI: string | null, localName: string): boolean;
68
}
69
```
70

71
**Usage Examples:**
72

73
```javascript
74
const { DOMParser } = require('xmldom');
75
const parser = new DOMParser();
76
const doc = parser.parseFromString(`
77
  <catalog xmlns="http://example.com/catalog"
78
           xmlns:product="http://example.com/product"
79
           xmlns:pricing="http://example.com/pricing">
80
    <product:item product:id="123">
81
      <product:name>Widget</product:name>
82
      <pricing:price pricing:currency="USD">29.99</pricing:price>
83
    </product:item>
84
  </catalog>
85
`, 'text/xml');
86

87
const item = doc.getElementsByTagNameNS('http://example.com/product', 'item').item(0);
88

89
// Get namespaced attributes
90
const productId = item.getAttributeNS('http://example.com/product', 'id');
91
console.log(productId); // "123"
92

93
// Set namespaced attributes
94
item.setAttributeNS('http://example.com/product', 'product:status', 'active');
95
item.setAttributeNS('http://example.com/pricing', 'pricing:discount', '10%');
96

97
// Check existence of namespaced attributes
98
console.log(item.hasAttributeNS('http://example.com/product', 'status')); // true
99
console.log(item.hasAttributeNS('http://example.com/product', 'missing')); // false
100

101
// Get child elements by namespace
102
const productElements = item.getElementsByTagNameNS('http://example.com/product', '*');
103
console.log(productElements.length); // Elements in product namespace
104

105
const priceElements = item.getElementsByTagNameNS('http://example.com/pricing', 'price');
106
console.log(priceElements.item(0).textContent); // "29.99"
107

108
// Remove namespaced attribute
109
item.removeAttributeNS('http://example.com/pricing', 'discount');
110
```
111

112
### Namespace-Aware Document Methods
113

114
Document interface extensions for creating namespaced elements, attributes, and querying by namespace.
115

116
```javascript { .api }
117
/**
118
 * Namespace-aware methods on Document interface
119
 */
120
interface Document extends Node {
121
  /**
122
   * Creates element with namespace URI and qualified name
123
   * @param namespaceURI The namespace URI or null for no namespace
124
   * @param qualifiedName The qualified name (prefix:localName or localName)
125
   * @returns New Element with specified namespace
126
   */
127
  createElementNS(namespaceURI: string | null, qualifiedName: string): Element;
128
  
129
  /**
130
   * Creates attribute with namespace URI and qualified name
131
   * @param namespaceURI The namespace URI or null for no namespace
132
   * @param qualifiedName The qualified name (prefix:localName or localName)
133
   * @returns New Attr with specified namespace
134
   */
135
  createAttributeNS(namespaceURI: string | null, qualifiedName: string): Attr;
136
  
137
  /**
138
   * Gets elements by namespace URI and local name from entire document
139
   * @param namespaceURI The namespace URI or "*" for any namespace
140
   * @param localName The local name or "*" for any name
141
   * @returns NodeList of matching elements
142
   */
143
  getElementsByTagNameNS(namespaceURI: string | null, localName: string): NodeList;
144
}
145
```
146

147
**Usage Examples:**
148

149
```javascript
150
const { DOMParser } = require('xmldom');
151
const parser = new DOMParser();
152
const doc = parser.parseFromString('<root></root>', 'text/xml');
153

154
// Create namespaced elements
155
const catalogNS = 'http://example.com/catalog';
156
const productNS = 'http://example.com/product';
157

158
const catalog = doc.createElementNS(catalogNS, 'catalog');
159
const product = doc.createElementNS(productNS, 'product:item');
160
const name = doc.createElementNS(productNS, 'product:name');
161

162
// Create namespaced attributes
163
const idAttr = doc.createAttributeNS(productNS, 'product:id');
164
idAttr.value = 'P001';
165

166
const statusAttr = doc.createAttributeNS(catalogNS, 'status');
167
statusAttr.value = 'active';
168

169
// Build document structure
170
name.appendChild(doc.createTextNode('Test Product'));
171
product.appendChild(name);
172
product.setAttributeNodeNS(idAttr);
173
catalog.appendChild(product);
174
catalog.setAttributeNodeNS(statusAttr);
175

176
// Replace document element
177
doc.replaceChild(catalog, doc.documentElement);
178

179
// Query by namespace
180
const productItems = doc.getElementsByTagNameNS(productNS, 'item');
181
console.log(productItems.length); // 1
182

183
const allProductElements = doc.getElementsByTagNameNS(productNS, '*');
184
console.log(allProductElements.length); // 2 (item and name)
185

186
// Verify namespace properties
187
console.log(product.namespaceURI); // "http://example.com/product"
188
console.log(product.localName); // "item" 
189
console.log(product.prefix); // "product"
190
console.log(product.nodeName); // "product:item"
191
```
192

193
### Node Namespace Properties
194

195
All nodes with namespace support provide properties for accessing namespace information.
196

197
```javascript { .api }
198
/**
199
 * Namespace properties on Node interface
200
 */
201
interface Node {
202
  /**
203
   * The namespace URI of the node, or null if unspecified
204
   */
205
  readonly namespaceURI: string | null;
206
  
207
  /**
208
   * The namespace prefix of the node, or null if unspecified
209
   */
210
  prefix: string | null;
211
  
212
  /**
213
   * The local name of the node (without namespace prefix)
214
   */
215
  readonly localName: string | null;
216
}
217
```
218

219
**Usage Examples:**
220

221
```javascript
222
const { DOMParser } = require('xmldom');
223
const parser = new DOMParser();
224
const doc = parser.parseFromString(`
225
  <root xmlns:ns1="http://example.com/ns1"
226
        xmlns:ns2="http://example.com/ns2">
227
    <ns1:element ns2:attribute="value">
228
      <ns1:child>content</ns1:child>
229
    </ns1:element>
230
  </root>
231
`, 'text/xml');
232

233
const element = doc.getElementsByTagNameNS('http://example.com/ns1', 'element').item(0);
234

235
// Access namespace properties
236
console.log(element.namespaceURI); // "http://example.com/ns1"
237
console.log(element.prefix); // "ns1"
238
console.log(element.localName); // "element"
239
console.log(element.nodeName); // "ns1:element"
240

241
// Check attribute namespace
242
const attr = element.getAttributeNodeNS('http://example.com/ns2', 'attribute');
243
console.log(attr.namespaceURI); // "http://example.com/ns2"
244
console.log(attr.prefix); // "ns2"
245
console.log(attr.localName); // "attribute"
246
console.log(attr.name); // "ns2:attribute"
247

248
// Modify prefix (changes nodeName but not namespaceURI)
249
element.prefix = 'changed';
250
console.log(element.nodeName); // "changed:element"
251
console.log(element.namespaceURI); // Still "http://example.com/ns1"
252
```
253

254
### Namespace Lookup Methods (DOM Level 3)
255

256
Advanced namespace resolution methods for looking up namespace URIs and testing default namespaces.
257

258
```javascript { .api }
259
/**
260
 * DOM Level 3 namespace lookup methods on Node interface
261
 */
262
interface Node {
263
  /**
264
   * Tests if given namespace URI is the default namespace
265
   * @param namespaceURI The namespace URI to test
266
   * @returns true if it's the default namespace
267
   */
268
  isDefaultNamespace(namespaceURI: string | null): boolean;
269
  
270
  /**
271
   * Looks up namespace URI for given prefix
272
   * @param prefix The namespace prefix to look up, or null for default namespace
273
   * @returns The namespace URI or null if not found
274
   */
275
  lookupNamespaceURI(prefix: string | null): string | null;
276
}
277
```
278

279
**Usage Examples:**
280

281
```javascript
282
const { DOMParser } = require('xmldom');
283
const parser = new DOMParser();
284
const doc = parser.parseFromString(`
285
  <root xmlns="http://example.com/default"
286
        xmlns:ns1="http://example.com/ns1"
287
        xmlns:ns2="http://example.com/ns2">
288
    <ns1:element>
289
      <child>Default namespace content</child>
290
      <ns2:item>NS2 content</ns2:item>
291
    </ns1:element>
292
  </root>
293
`, 'text/xml');
294

295
const element = doc.getElementsByTagNameNS('http://example.com/ns1', 'element').item(0);
296
const child = element.getElementsByTagName('child').item(0);
297

298
// Test default namespace
299
console.log(child.isDefaultNamespace('http://example.com/default')); // true
300
console.log(child.isDefaultNamespace('http://example.com/ns1')); // false
301

302
// Look up namespace URIs
303
console.log(element.lookupNamespaceURI('ns1')); // "http://example.com/ns1"
304
console.log(element.lookupNamespaceURI('ns2')); // "http://example.com/ns2"
305
console.log(element.lookupNamespaceURI(null)); // "http://example.com/default"
306
console.log(element.lookupNamespaceURI('undefined')); // null
307
```
308

309
### NamedNodeMap Namespace Support
310

311
NamedNodeMap (attribute collections) provides namespace-aware methods for managing attributes.
312

313
```javascript { .api }
314
/**
315
 * Namespace-aware methods on NamedNodeMap interface
316
 */
317
interface NamedNodeMap {
318
  /**
319
   * Gets named item by namespace URI and local name
320
   * @param namespaceURI The namespace URI or null for no namespace
321
   * @param localName The local name of the item
322
   * @returns Node or null if not found
323
   */
324
  getNamedItemNS(namespaceURI: string | null, localName: string): Node | null;
325
  
326
  /**
327
   * Sets named item with namespace support
328
   * @param arg The Node to set
329
   * @returns Previous Node or null
330
   */
331
  setNamedItemNS(arg: Node): Node | null;
332
  
333
  /**
334
   * Removes named item by namespace URI and local name
335
   * @param namespaceURI The namespace URI or null for no namespace
336
   * @param localName The local name of the item
337
   * @returns Removed Node
338
   */
339
  removeNamedItemNS(namespaceURI: string | null, localName: string): Node;
340
}
341
```
342

343
**Usage Examples:**
344

345
```javascript
346
const { DOMParser } = require('xmldom');
347
const parser = new DOMParser();
348
const doc = parser.parseFromString('<root></root>', 'text/xml');
349

350
const element = doc.createElement('test');
351
const attrs = element.attributes;
352

353
// Create namespaced attributes
354
const ns1Attr = doc.createAttributeNS('http://example.com/ns1', 'ns1:attr1');
355
ns1Attr.value = 'value1';
356

357
const ns2Attr = doc.createAttributeNS('http://example.com/ns2', 'ns2:attr2');
358
ns2Attr.value = 'value2';
359

360
const defaultAttr = doc.createAttribute('defaultAttr');
361
defaultAttr.value = 'defaultValue';
362

363
// Set attributes using NamedNodeMap
364
attrs.setNamedItemNS(ns1Attr);
365
attrs.setNamedItemNS(ns2Attr);
366
attrs.setNamedItem(defaultAttr);
367

368
console.log(attrs.length); // 3
369

370
// Access by namespace
371
const retrievedNS1 = attrs.getNamedItemNS('http://example.com/ns1', 'attr1');
372
console.log(retrievedNS1.value); // "value1"
373

374
const retrievedNS2 = attrs.getNamedItemNS('http://example.com/ns2', 'attr2');
375
console.log(retrievedNS2.value); // "value2"
376

377
// Access default namespace attribute
378
const retrievedDefault = attrs.getNamedItemNS(null, 'defaultAttr');
379
console.log(retrievedDefault.value); // "defaultValue"
380

381
// Remove by namespace
382
const removed = attrs.removeNamedItemNS('http://example.com/ns1', 'attr1');
383
console.log(removed.value); // "value1"
384
console.log(attrs.length); // 2
385
```
386

387
### Default Namespace Handling
388

389
Special handling for default namespace declarations and inheritance.
390

391
```javascript { .api }
392
// Default namespace is declared with xmlns="uri"
393
// Elements without prefix inherit the default namespace
394
// Attributes never inherit default namespace (always null unless explicitly namespaced)
395
```
396

397
**Usage Examples:**
398

399
```javascript
400
const { DOMParser, XMLSerializer } = require('xmldom');
401
const parser = new DOMParser();
402
const serializer = new XMLSerializer();
403

404
// Document with default namespace
405
const doc = parser.parseFromString(`
406
  <catalog xmlns="http://example.com/catalog">
407
    <product>
408
      <name>Widget</name>
409
    </product>
410
    <external xmlns="http://example.com/external">
411
      <item>External item</item>
412
    </external>
413
  </catalog>
414
`, 'text/xml');
415

416
// Elements inherit default namespace
417
const catalog = doc.documentElement;
418
console.log(catalog.namespaceURI); // "http://example.com/catalog"
419
console.log(catalog.localName); // "catalog"
420
console.log(catalog.prefix); // null
421

422
const product = catalog.getElementsByTagName('product').item(0);
423
console.log(product.namespaceURI); // "http://example.com/catalog" (inherited)
424

425
const external = catalog.getElementsByTagName('external').item(0);
426
console.log(external.namespaceURI); // "http://example.com/external" (redeclared)
427

428
const item = external.getElementsByTagName('item').item(0);
429
console.log(item.namespaceURI); // "http://example.com/external" (inherited)
430

431
// Create new document with default namespace
432
const newDoc = parser.parseFromString('<root></root>', 'text/xml');
433
const catalogElement = newDoc.createElementNS('http://example.com/catalog', 'catalog');
434
catalogElement.setAttribute('xmlns', 'http://example.com/catalog');
435

436
const productElement = newDoc.createElementNS('http://example.com/catalog', 'product');
437
catalogElement.appendChild(productElement);
438

439
newDoc.replaceChild(catalogElement, newDoc.documentElement);
440

441
console.log(serializer.serializeToString(newDoc));
442
// Produces proper default namespace declaration
443
```