Namespaces en XML: guía práctica para evitar conflictos (SOAP, RSS, sitemaps)

Qué es un namespace en XML (explicado sin humo)

Un namespace en XML es una forma de evitar colisiones de nombres. Piensa en dos equipos diferentes que usan la etiqueta <id>: uno la usa para “id de usuario” y otro para “id de pedido”. Si mezclas esos documentos, el nombre id se vuelve ambiguo. El namespace resuelve eso asociando cada nombre a una URI.

En la práctica, se ve así:

<root xmlns:crm="https://ejemplo.com/crm"
      xmlns:shop="https://ejemplo.com/shop">
  <crm:id>U-123</crm:id>
  <shop:id>O-987</shop:id>
</root>

Los prefijos (crm, shop) son solo “alias”. Lo que importa de verdad es la URI declarada.

Por qué te importa en SOAP, RSS y sitemaps

Namespaces aparecen en casi todo lo serio:

• SOAP: soap:Envelope y amigos viven en un namespace específico.
• RSS/Atom: extensiones como content, media, dc se declaran por namespaces.
• Sitemaps: el namespace del sitemap es obligatorio, y los “image sitemap” y “news sitemap” usan namespaces adicionales.

Cuando un namespace está mal, los parsers suelen dar errores confusos o, peor, “funciona pero no lo lee el consumidor”.

El error clásico: “prefix is not bound”

Este error aparece cuando usas un prefijo sin declararlo:

<soap:Envelope>...</soap:Envelope>

Si no existe xmlns:soap="..." en el elemento raíz (o en un ancestro), el documento es inválido. La solución típica en SOAP 1.1:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

Y en SOAP 1.2 cambia a http://www.w3.org/2003/05/soap-envelope.

Namespace por defecto (sin prefijo)

También puedes declarar un namespace “por defecto” (sin prefijo):

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>...</url>
</urlset>

Ojo: esto significa que <url> NO está en “namespace vacío”; está en el namespace del sitemap. Este detalle rompe muchas consultas XPath (luego volvemos a eso).

Cómo depurar namespaces rápido

Cuando algo “no se lee”:

1. Busca el root y lista todos los xmlns.
2. Comprueba que los prefijos usados están declarados.
3. Verifica que la URI es exactamente la esperada (una letra diferente y el consumidor lo ignora).
4. Valida el documento con un parser estricto para ver si hay errores de well‑formed.

Puedes hacerlo en segundos con nuestra herramienta Validador de XML: pega el documento, valida y formatea para inspeccionar el root y sus declaraciones.

Ejemplos reales

Sitemap con imágenes

Un sitemap básico declara el namespace principal. Si además incluyes imágenes, necesitas un namespace extra:

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">
  <url>
    <loc>https://example.com/</loc>
    <image:image>
      <image:loc>https://example.com/img.jpg</image:loc>
    </image:image>
  </url>
</urlset>

RSS con Dublin Core

<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <item>
      <dc:creator>Ivan</dc:creator>
    </item>
  </channel>
</rss>

Namespaces y XPath: el combo que más confunde

Si tu XML usa namespace por defecto, XPath necesita que lo declares en el contexto de consulta. Mucha gente intenta:

//url

…y no encuentra nada, porque en realidad el nodo es {http://www.sitemaps.org/schemas/sitemap/0.9}url. En herramientas XPath, sueles mapear el namespace a un prefijo (por ejemplo sm) y consultar:

//sm:url

Esto es crucial para depurar integraciones que “no encuentran” nodos.

Buenas prácticas al diseñar XML con namespaces

• Usa namespaces estables: la URI debe ser persistente. No tiene que ser una URL “viva”, pero sí estable.
• No abuses de prefijos: define prefijos claros y pocos. Evita ns1, ns2 si puedes.
• Documenta qué namespace corresponde a qué parte del contrato.
• Valida en CI si generas XML: namespaces mal puestos generan bugs silenciosos.

Problemas de compatibilidad (y cómo resolverlos)

Un consumidor antiguo no acepta namespaces

Algunos sistemas legacy esperan XML “simple” sin namespaces. Si no puedes cambiarlos, quizá debas generar una variante “legacy” sin namespaces o con un esquema específico. Evita mezclar ambos contratos: versiona.

Se rompe al transformar (XSLT) o al serializar

En transformaciones, asegúrate de copiar también declaraciones xmlns. Si una plantilla XSLT crea nodos con prefijo pero no declara el namespace, vuelves al error “prefix not bound”.

Checklist

• ¿Todos los prefijos usados están declarados?
• ¿Las URIs son exactas?
• ¿Hay namespace por defecto? (impacta XPath)
• ¿SOAP 1.1 vs 1.2 correcto?
• ¿El consumidor documenta namespaces obligatorios?

Conclusión

Namespaces parecen un detalle, pero son la base de muchas integraciones robustas. Si los entiendes, depurar SOAP, RSS o sitemaps se vuelve mucho más rápido. Cuando tengas dudas, valida y formatea el XML, revisa las declaraciones xmlns y asegúrate de que tus consultas XPath usan el namespace correcto.

Cómo funciona el “scope” de un namespace

Una declaración xmlns aplica al elemento donde aparece y a todos sus descendientes, salvo que se re‑declare. Esto permite acotar namespaces por secciones:

<root xmlns:a="urn:a">
  <a:one/>
  <block xmlns:b="urn:b">
    <b:two/>
  </block>
</root>

En este ejemplo, b solo existe dentro de <block>. Si intentas usar <b:two> fuera, el documento es inválido.

Namespaces en atributos

Los atributos también pueden pertenecer a namespaces, pero hay un matiz importante: el namespace por defecto no se aplica a atributos. Es decir, si tienes:

<root xmlns="urn:x" id="1">

El elemento root está en urn:x, pero el atributo id NO. Si quieres un atributo con namespace, debes usar prefijo:

<root xmlns:x="urn:x" x:id="1">

El namespace reservado xml y xmlns

Hay dos prefijos especiales:

• xml está reservado y siempre mapea a http://www.w3.org/XML/1998/namespace. Lo verás en xml:lang o xml:space.
• xmlns se usa para declarar namespaces; no es un prefijo “normal”.

Si alguien intenta redefinirlos, el parser lo rechazará.

Ejemplo SOAP con múltiples namespaces

Una respuesta SOAP típica mezcla al menos dos namespaces: el del envelope y el del servicio:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
              xmlns:svc="https://api.ejemplo.com/servicio">
  <soap:Body>
    <svc:GetStatusResponse>
      <svc:status>OK</svc:status>
    </svc:GetStatusResponse>
  </soap:Body>
</soap:Envelope>

Si el proveedor cambia la URI del namespace del servicio (aunque los nombres de nodos se vean iguales), tu cliente puede dejar de “encontrar” nodos. Esto ocurre mucho con integraciones versionadas por URL.

Cómo consultar con DOMXPath en PHP (el punto donde muchos se atascan)

Cuando usas DOMXPath, debes registrar los namespaces manualmente. Ejemplo: extraer svc:status del SOAP anterior:

<?php
$dom = new DOMDocument();
$dom->loadXML($xml, LIBXML_NONET);
$xp = new DOMXPath($dom);
$xp->registerNamespace('soap', 'http://schemas.xmlsoap.org/soap/envelope/');
$xp->registerNamespace('svc', 'https://api.ejemplo.com/servicio');
$status = $xp->evaluate('string(/soap:Envelope/soap:Body/svc:GetStatusResponse/svc:status)');

Si olvidas registerNamespace, XPath no devolverá resultados y parecerá que “no existe” el nodo.

Truco para depurar XPath cuando hay namespace por defecto

Un truco rápido es asignar un prefijo “inventado” al namespace por defecto para poder consultarlo. Por ejemplo, en un sitemap:

• Namespace por defecto: http://www.sitemaps.org/schemas/sitemap/0.9
• Prefijo que asignas tú: sm

Consulta:

//sm:loc

Esto aplica igual para XML de facturación, respuestas de servicios y cualquier contrato que use namespace sin prefijo.

Errores silenciosos: el XML “valida” pero el consumidor no interpreta

Este es el caso más frustrante: el XML está bien formado, incluso puede pasar un esquema, pero el consumidor no “ve” los datos. Causas típicas:

• URI de namespace incorrecta o diferente a la documentada.
• Prefijo correcto, pero declarado apuntando a otra URI.
• El consumidor usa XPath sin namespaces (bug en el consumidor) y por eso ignora nodos con namespace por defecto.

En estos casos, lo más útil es: formatear, revisar el root y comparar literalmente las URIs con la documentación o con ejemplos que sí funcionan.

FAQ

¿La URI del namespace tiene que existir como URL?

No. Es un identificador. Puede ser una URL que no responde, y aun así es válido. Lo importante es que sea estable y única.

¿Puedo cambiar prefijos y mantener la misma URI?

Sí. El prefijo es un alias local. Puedes cambiar svc por s mientras la URI sea la misma. Algunos consumidores mal implementados comparan prefijos, pero no deberían.

¿Qué pasa si mezclo namespaces en el mismo documento?

Es normal. Solo asegúrate de declararlos y de que cada parte del documento usa el namespace esperado. En SOAP es lo habitual.

Si tienes un XML que falla por namespaces, pégalo y revísalo con nuestro validador: validar + formatear te deja a la vista todas las declaraciones xmlns para detectar el problema.

Versionado de namespaces: una estrategia que evita dolores

Hay proveedores que versionan el contrato cambiando la URI del namespace (por ejemplo, .../v1, .../v2). Es válido y, de hecho, es una buena señal porque permite coexistencia de versiones. El problema aparece cuando:

• La documentación dice v1 pero el entorno real ya responde v2.
• Tu cliente tiene el namespace “hardcodeado” y deja de encontrar nodos.
• Se mezclan partes v1 y v2 en un mismo mensaje.

Si estás diseñando tú el XML, decide si versionas por namespace o por elemento raíz. Y si consumes un tercero, prepara tu parser para soportar varias URIs (por ejemplo, registrando ambas y probando).

Cómo localizar rápidamente dónde se declara un namespace

En XML grandes, encontrar el xmlns a ojo es lento. Dos trucos:

• Formatea el XML y colapsa secciones en el editor para ir al root.
• Busca literalmente xmlns: (o xmlns= para el default). Casi siempre está en el root.

Una vez localizado, compara la URI con un ejemplo “bueno”. Un simple carácter de diferencia equivale a un namespace diferente.

Resumen práctico: en XML, el nombre real de un nodo es “namespace + localName”. Si algo no se encuentra, no asumas que el nodo no existe: revisa namespaces, registra prefijos en XPath y valida el documento. En integraciones, el 80% de los “misterios” de XML se resuelven mirando bien las URIs.

Cuando dominas esto, SOAP deja de parecer magia negra y pasa a ser un árbol bien definido con etiquetas y URIs. Y eso se depura rápido.

Prueba tus documentos con el validador y te ahorrarás muchos tickets.