Cómo Validar XML Contra un Esquema XSD: Errores, Herramientas y CI/CD

XSD significa XML Schema Definition. Es un estándar del W3C que permite describir la estructura exacta que debe seguir un documento XML: qué elementos están permitidos, en qué orden aparecen, a qué tipos de datos debe ajustarse su contenido y qué atributos son obligatorios u opcionales. Cuando validas un documento XML contra un XSD, un parser lee ambos archivos e informa de cada punto en que el documento se desvía del contrato del esquema.

XSD reemplazó al antiguo formato DTD (Document Type Definition) como lenguaje principal de esquemas XML porque está escrito él mismo en XML, soporta un rico conjunto de tipos de datos integrados (`xs:integer`, `xs:date`, `xs:boolean`, etc.) y puede expresar restricciones complejas como patrones de cadena, rangos numéricos y requisitos condicionales de elementos. Los DTD todavía se encuentran en sistemas heredados, pero XSD es el estándar para cualquier intercambio de datos basado en XML construido en los últimos quince años.

Dónde se usa la validación XSD

La validación XSD aparece dondequiera que datos XML estructurados cruzan un límite de sistema. Ejemplos comunes incluyen las peticiones y respuestas de servicios web SOAP (descritas por WSDL, que incrusta esquemas XSD), los formatos de facturación electrónica y adquisiciones como UBL 2.1 y EDIFACT, el intercambio de datos sanitarios con perfiles XML HL7 CDA y FHIR, las declaraciones XML gubernamentales (impuestos, aduanas) y los archivos de configuración de software empresarial como el `pom.xml` de Maven o el XML de contexto de aplicación de Spring.

• Servicios SOAP / WSDL: cada elemento de petición y respuesta está definido en un XSD incrustado.
• Facturación electrónica (UBL, CII): los formatos de adquisición y facturas llevan esquemas XSD públicos contra los que validan los socios comerciales.
• Sanidad (HL7, FHIR XML): el intercambio de documentos clínicos exige conformidad XSD estricta antes de la aceptación.
• Declaraciones gubernamentales: las agencias tributarias y aduaneras publican esquemas XSD que los documentos presentados deben satisfacer.
• Herramientas de build: el pom.xml de Maven, el build.xml de Ant y muchos otros formatos de configuración usan XSD para el autocompletado y la validación del IDE.

Todo documento XML debe tener primero buen formato antes de poder validarse. El buen formato lo comprueba el propio parser XML, sin necesidad de esquema. La validez es una capa adicional que se comprueba contra un esquema específico. Entender la distinción ahorra mucho tiempo de depuración: un validador XSD que recibe un documento mal formado a menudo informa de errores de esquema confusos en lugar del verdadero problema de parseo.

Un objeto textual es un documento XML con buen formato si coincide con la producción etiquetada como document y satisface todas las restricciones de buen formato dadas en la especificación.

Qué comprueba el buen formato

• Emparejamiento de etiquetas: cada etiqueta de apertura tiene su correspondiente etiqueta de cierre (`<item>` → `</item>`).
• Anidamiento correcto: las etiquetas deben cerrarse en orden inverso: `<a><b></b></a>` es válido; `<a><b></a></b>` no lo es.
• Un único elemento raíz: el documento tiene exactamente un elemento de nivel superior.
• Atributos entre comillas: todos los valores de atributo van entre comillas simples o dobles.
• Caracteres especiales escapados: `<`, `>`, `&`, `"` y `'` dentro del contenido de texto deben usar referencias de entidad o secciones CDATA.
• Nombres de elementos y atributos válidos: los nombres empiezan por letra o guion bajo, no por dígito o guion.

Qué añade la validez XSD por encima

Una vez superado el buen formato, la validación XSD superpone el contrato del esquema. Esto incluye comprobar que cada elemento declarado como obligatorio con `minOccurs="1"` está realmente presente, que el contenido de texto de los elementos con tipo coincide con el `xs:type` declarado (nada de cadenas en campos enteros), que los valores numéricos caen dentro de los límites `xs:minInclusive` y `xs:maxInclusive`, que el contenido de cadena satisface las restricciones regex `xs:pattern`, y que los elementos hijos aparecen en la secuencia, elección o grupo completo definido en el esquema.

Antes de poder validar XML contra un XSD, necesitas entender qué contiene un archivo XSD. Un archivo de esquema es él mismo un documento XML válido, con un elemento raíz `xs:schema` en el namespace `http://www.w3.org/2001/XMLSchema`. Todo lo que hay dentro del esquema describe cómo deben ser los documentos XML de destino.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <!-- Root element declaration --&gt;
  <xs:element name="Invoice">
    <xs:complexType>
      <xs:sequence>
        <!-- Required string - must be present exactly once --&gt;
        <xs:element name="InvoiceNumber" type="xs:string" minOccurs="1" maxOccurs="1"/>
        <!-- Required date --&gt;
        <xs:element name="IssueDate"     type="xs:date"   minOccurs="1" maxOccurs="1"/>
        <!-- Required positive integer --&gt;
        <xs:element name="TotalAmount"   type="xs:decimal" minOccurs="1" maxOccurs="1"/>
        <!-- Optional - 0 to many line items --&gt;
        <xs:element name="LineItem"      type="LineItemType" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
      <!-- Required attribute --&gt;
      <xs:attribute name="currency" type="xs:string" use="required"/>
    </xs:complexType>
  </xs:element>

  <!-- Reusable complex type definition --&gt;
  <xs:complexType name="LineItemType">
    <xs:sequence>
      <xs:element name="Description" type="xs:string"/>
      <xs:element name="Quantity"    type="xs:positiveInteger"/>
      <xs:element name="UnitPrice"   type="xs:decimal"/>
    </xs:sequence>
  </xs:complexType>

</xs:schema>

Conceptos clave de XSD

• xs:element: declara un elemento por nombre y tipo. `minOccurs` y `maxOccurs` controlan la cardinalidad.
• xs:complexType: define un elemento que contiene elementos hijos o atributos (no solo texto).
• xs:simpleType: define un tipo derivado de un tipo integrado; se usa para añadir restricciones como patrones o enumeraciones.
• xs:sequence: los elementos hijos deben aparecer en el orden exacto listado.
• xs:choice: debe aparecer exactamente uno de los elementos hijos listados.
• xs:all: todos los elementos hijos listados deben aparecer, en cualquier orden, cada uno exactamente una vez.
• xs:attribute: declara un atributo en un elemento complejo. `use="required"` lo hace obligatorio.
• xs:restriction: añade restricciones a un tipo base: `xs:pattern`, `xs:minInclusive`, `xs:enumeration`, etc.

Hay tres formas prácticas de validar un documento XML contra un esquema XSD: una herramienta basada en navegador para comprobaciones rápidas, una herramienta de línea de comandos para desarrollo local y scripting, y un enfoque programático para integrarlo en el código de la aplicación o en pipelines de CI. Los tres enfoques informan de las mismas categorías de errores; la diferencia está en dónde y cómo ejecutas la validación.

# Validate document.xml against schema.xsd using xmllint
xmllint --schema schema.xsd document.xml --noout

# Output on success:
document.xml validates

# Output on failure:
document.xml:12: element TotalAmount: Schemas validity error:
Element 'TotalAmount': 'abc' is not a valid value of the
atomic type 'xs:decimal'.

Los errores de validación XSD caen en categorías previsibles. Entender qué significa cada tipo de error te permite localizar y corregir el problema en el documento de origen rápidamente, en lugar de descifrar salida desconocida del validador línea por línea.

Errores de discrepancia de tipos

Los errores de tipo ocurren cuando el contenido de un elemento o atributo no coincide con el `xs:type` declarado. Los más comunes: una cadena de texto como `"N/A"` en un campo declarado como `xs:integer`, una fecha en formato erróneo (por ejemplo, `15/06/2026` en lugar de `2026-06-15`) en un campo `xs:date`, o un decimal en un campo declarado como `xs:positiveInteger`. Corrígelo ajustando el valor en el documento de origen o modificando la declaración de tipo en el esquema si el tipo actual es demasiado restrictivo.

Elementos obligatorios ausentes

Cuando `minOccurs="1"` (el valor por defecto de `xs:element`) y el elemento está ausente del documento de instancia, el validador informa: `Element 'X': This element is not expected. Expected is one of ( Y )` o `Element 'X' is missing`. Esto normalmente significa que el productor del XML omitió un campo obligatorio. Consulta el `xs:sequence` del esquema para confirmar qué elementos son obligatorios y en qué posición.

Elementos inesperados o no declarados

Si tu esquema no usa `xs:any` ni establece `processContents="lax"`, cualquier elemento no declarado en el esquema producirá: `Element 'X': This element is not expected`. Este es el error más común cuando un productor de XML añade un campo nuevo sin actualizar el esquema, o cuando el documento contiene un prefijo de namespace no declarado. Comprueba el nombre del elemento, el contexto del elemento padre y las declaraciones de namespace en la cabecera del documento.

Violaciones de patrón y enumeración

XSD soporta `xs:pattern` (una regex) y `xs:enumeration` (una lista de valores permitidos) como facetas en tipos simples. Una violación se ve así: `Element 'Status': [facet 'enumeration'] The value 'ACTIVE' is not an element of the set active', 'inactive', 'pending`. Comprueba si el esquema usa valores de enumeración sensibles a mayúsculas y si el documento de instancia coincide exactamente con las mayúsculas esperadas.

La validación manual sirve para comprobaciones puntuales, pero los flujos XML de producción necesitan validación automatizada en cada punto de integración. Añadir validación XSD a tu código de aplicación y pipeline de CI garantiza que los documentos inválidos se rechacen antes de que causen corrupción de datos, fallos de procesamiento o incumplimientos normativos aguas abajo.

Validar en Python con lxml

from lxml import etree

def validate_against_xsd(xml_path: str, xsd_path: str) -> list[str]:
    """Returns a list of validation error messages, empty if valid."""
    with open(xsd_path, 'rb') as f:
        schema_doc = etree.parse(f)
    schema = etree.XMLSchema(schema_doc)

    with open(xml_path, 'rb') as f:
        doc = etree.parse(f)

    schema.validate(doc)
    return [str(e) for e in schema.error_log]

errors = validate_against_xsd('invoice.xml', 'invoice.xsd')
if errors:
    for err in errors:
        print(err)
else:
    print('Document is valid.')

Añadir validación XSD a GitHub Actions

Para flujos CI/CD que procesan o generan XML, un paso de validación evita que documentos rotos se fusionen. El comando `xmllint` está disponible en los runners Ubuntu de GitHub Actions mediante `sudo apt-get install -y libxml2-utils`. Añade un paso que ejecute `xmllint --schema schema.xsd document.xml --noout` en cada pull request que toque archivos XML. Un código de salida distinto de cero hace fallar la comprobación y bloquea la fusión.

name: Validate XML
on:
  pull_request:
    paths:
      - '**/*.xml'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install xmllint
        run: sudo apt-get install -y libxml2-utils
      - name: Validate XML against XSD
        run: |
          xmllint --schema schemas/invoice.xsd \
                  data/invoices/*.xml \
                  --noout

Usar XPath para inspeccionar valores concretos antes de validar

Antes de ejecutar una pasada XSD completa, puedes usar el Buscador y Probador de XPath para localizar el valor de un elemento o atributo específico en un documento XML grande. Consultas XPath como `//Invoice/TotalAmount/text()` recuperan un campo sin tener que analizar el archivo entero a mano. Esto es especialmente útil al diagnosticar una discrepancia de tipos en un documento con cientos de elementos: localiza primero el valor problemático y aplica después la corrección.

Comparación de enfoques de validación

Un esquema XSD bien diseñado hace que los documentos sean más fáciles de validar, de extender y de mantener entre versiones del esquema. Estas prácticas aplican tanto si autoras un esquema desde cero como si mantienes uno recibido de un socio externo.

Usa tipos con nombre en lugar de tipos anónimos en línea

Define los tipos complejos con `xs:complexType name="..."` en lugar de anidarlos anónimamente dentro de las declaraciones de elementos. Los tipos con nombre pueden reutilizarse en múltiples declaraciones de elementos, reduciendo la repetición y facilitando los cambios de esquema: actualiza la definición del tipo una vez y todos los elementos que lo usan heredan el cambio.

Prefiere xs:sequence sobre xs:all en contratos estrictos

`xs:all` permite que los elementos aparezcan en cualquier orden, lo que parece permisivo pero introduce ambigüedad para productores y consumidores. `xs:sequence` es más explícito y coincide con el orden natural de lectura de la mayoría de formatos XML. Usa `xs:all` solo cuando el orden de los elementos genuinamente no importe y autoras el esquema para un sistema que controlas; prefiere `xs:sequence` en cualquier esquema que cruce fronteras organizativas.

Versiona tus esquemas con un namespace

Usa un URI de target namespace que incluya un indicador de versión, como `targetNamespace="urn:example:invoice:v2"`. Esto hace explícitos los cambios de esquema que rompen compatibilidad: los consumidores en v1 verán un mismatch de namespace en lugar de validar silenciosamente contra la versión equivocada del esquema. Mantén el esquema antiguo disponible para despliegues retrocompatibles durante la ventana de migración.

• Declara un targetNamespace: evita colisiones de nombres de elementos cuando los esquemas se componen mediante xs:import.
• Usa xs:documentation: añade descripciones legibles dentro de bloques xs:annotation para que los consumidores del esquema entiendan cada campo.
• Fija minOccurs/maxOccurs explícitos: nunca dependas del valor por defecto; indica la cardinalidad explícitamente para comunicar la intención.
• Usa xs:restriction para cadenas restringidas: un campo de código postal debería usar xs:pattern, no xs:string; la validación atrapa errores de formato en el límite.
• Divide esquemas grandes: usa xs:include para partir un esquema de 500 líneas en archivos por dominio (addresses.xsd, line-items.xsd) y facilitar el mantenimiento.