XML to Dictionary

XML to Dictionary

Tipo: xml-to-dictionary  ·  Paquete: XML Activities v1.1.1  ·  Salida: Dictionary<string,object>

Desde: v1.1.1

Convierte un documento XML en un diccionario que recorres con expresiones, igual que un JSON leído con Read JSON: factura["ID"], factura["InvoiceLine"][0]["ID"]. Úsala cuando necesitas muchos datos de un mismo XML: en lugar de una consulta XPath por dato, conviertes una vez y lees lo que quieras. En el Designer en español aparece como «XML a diccionario».

Cómo funciona

Lee el XML de xml (texto) o de path (archivo; respeta la codificación que declare, p. ej. ISO-8859-1) y devuelve el contenido del elemento raíz —o del elemento que elija xpath—. El nombre del propio elemento no aparece como clave: el diccionario son directamente sus atributos, su texto y sus hijos. Las reglas:

En el XML	En el diccionario
<cbc:ID>FE-1001</cbc:ID>	"ID": "FE-1001" (texto)
Elemento con atributos <cbc:PayableAmount currencyID="COP">1785000.00</…>	"PayableAmount": { "@currencyID": "COP", "#text": "1785000.00" }
Elemento con atributos y sin texto <e x="2"/>	"e": { "@x": "2", "#text": "" }
Elemento con hijos	Un diccionario con sus hijos (y sus atributos @…)
Hijos repetidos (<cac:InvoiceLine> × 2)	Una lista en el orden del documento
Elemento vacío <cbc:Note/>	""
Texto suelto entre hijos (contenido mixto)	"#text", con los trozos de texto unidos
Sección CDATA	Su contenido, como texto
Declaraciones xmlns:…	No aparecen (no son datos)

El resultado es siempre un diccionario: si el elemento solo tiene texto, ese texto queda en "#text". Las claves salen en el orden de primera aparición en el documento.

Un ejemplo completo. Este XML:

<Pedido numero="P-77">
  <Cliente>Comercial Andina</Cliente>
  <Linea><Codigo>A-1</Codigo><Cantidad>2</Cantidad></Linea>
  <Linea><Codigo>B-7</Codigo><Cantidad>1</Cantidad></Linea>
  <Total moneda="USD">150.00</Total>
  <Nota/>
</Pedido>

da este diccionario:

{
  "@numero": "P-77",
  "Cliente": "Comercial Andina",
  "Linea": [
    { "Codigo": "A-1", "Cantidad": "2" },
    { "Codigo": "B-7", "Cantidad": "1" }
  ],
  "Total": { "@moneda": "USD", "#text": "150.00" },
  "Nota": ""
}

Prefijos y colisiones

• Por defecto las claves van sin prefijo (ID, InvoiceLine). Con keepPrefixes = true van como en el documento (cbc:ID, cac:InvoiceLine).
• Si dos hijos de namespaces distintos darían la misma clave (p. ej. a:ID y b:ID), todos los de esa colisión conservan su prefijo: a:ID y b:ID. Un elemento del namespace por defecto usa el prefijo de defaultPrefix (d:ID). Si aun así coinciden (el mismo prefijo declarado con dos URI distintas, o el documento ya usa d para otro namespace), la clave es {uri}nombre. La regla es la misma para los atributos (@type y @xsi:type).
• La regla es determinista: el mismo XML da siempre las mismas claves, en el orden del documento.

Listas siempre

Un elemento que a veces se repite (las líneas de una factura) es lista cuando hay varios y diccionario (o texto) cuando hay uno. Para recorrerlo siempre igual, ponlo en forceList: ["InvoiceLine"]. Sirve el nombre con o sin prefijo (InvoiceLine o cac:InvoiceLine) y la regla aplica a ese nombre en cualquier nivel del documento.

Valores: texto exacto

Todos los valores quedan como texto exacto: 1785000.00 sigue siendo "1785000.00", sin perder ceros ni precisión, y los códigos con ceros a la izquierda (01) no cambian. Si activas convertTypes (también aplica a los atributos):

• Enteros → número entero (900000001); lo que empieza por 0 (salvo el propio 0) sigue como texto.
• Decimales con punto → número decimal exacto (1785000.00 conserva sus dos decimales); si tiene más dígitos de los que caben sin redondear, se queda como texto.
• Fechas ISO → fecha: 2026-10-30 y 2026-09-30T10:15:00 como fecha y hora sin zona; 2026-09-30T10:15:00-05:00 o …Z como fecha con zona horaria.
• Todo lo demás sigue como texto: +5, 1e5, true, horas sueltas (10:15:00), textos de más de 64 caracteres y los vacíos.

Parámetros requeridos

Ninguno. Debes indicar uno de xml o path (no los dos).

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
xml	string	—	Texto XML. También el XML embebido que sale de un CDATA (ver el ejemplo). Usa este o path.
path	string	—	Ruta de un archivo XML. Usa este o xml.
xpath	string	—	XPath del elemento que se convierte, si solo necesitas un fragmento, p. ej. "//cac:AccountingSupplierParty". Se toma la primera coincidencia. Sin valor, el elemento raíz.
keepPrefixes	bool	false	Conserva los prefijos de namespace en las claves (cbc:ID en lugar de ID). Desactivado, solo llevan prefijo los nombres que chocarían.
forceList	List | string	—	Nombres de elementos que siempre son lista, aunque haya uno solo: una lista (["InvoiceLine"]) o un texto separado por comas ("InvoiceLine, Note").
convertTypes	bool	false	Convierte números y fechas ISO en valores numéricos y de fecha. Desactivado, todo queda como texto exacto.
namespaces	Dictionary	—	Prefijos extra o que reemplazan a los del documento para el xpath (prefijo → URI). Ver Namespaces.
defaultPrefix	string	"d"	Prefijo del namespace por defecto en el xpath y en las claves que chocan. Vacío equivale a "d".

Salida

Devuelve un Dictionary<string,object> cuyos valores son texto, diccionarios (Dictionary<string,object>) y listas (List); con convertTypes, también números y fechas.

Si xpath no encuentra nada, la salida es null (no falla) y el log deja un aviso. Compruébalo antes de leer claves.

Errores comunes

Mensaje	Causa y solución
Indica el texto XML ('xml') o el archivo ('path').	No se indicó ninguno de los dos (o los dos quedaron vacíos).
Usa 'xml' o 'path', no los dos.	Se indicaron ambos. Deja solo uno.
No se encontró el archivo: …	La ruta de path no existe.
El XPath debe seleccionar un elemento.	El xpath apunta a un atributo, un texto o un valor calculado. Apunta al elemento que lo contiene.
'keepPrefixes' debe ser true o false. / 'convertTypes' debe ser true o false.	La expresión del parámetro no dio un booleano ni el texto true/false.
Mensaje del analizador XML / DTD / tamaño / anidamiento / prefijo	Ver Errores comunes del paquete.

Un elemento que el XML no trae simplemente no aparece como clave: si es opcional en tus documentos, comprueba que esté antes de leerlo.

Ejemplo: factura electrónica embebida (datos ficticios)

La factura electrónica de Colombia (DIAN, UBL 2.1) suele llegar como un AttachedDocument que lleva la factura real como texto dentro de cac:Attachment/cac:ExternalReference/cbc:Description. Son dos pasos: sacar ese texto y convertirlo.

Read XML   path = rutaXml   → output: contenedor
XML Query Text
  xml = contenedor
  xpath = "//cac:Attachment/cac:ExternalReference/cbc:Description"
  → output: facturaXml
XML to Dictionary
  xml = facturaXml
  forceList = "InvoiceLine"
  → output: factura
Set Variable   name = nit      value = factura["AccountingSupplierParty"]["Party"]["PartyTaxScheme"]["CompanyID"]["#text"]
Set Variable   name = numero   value = factura["ID"]
Set Variable   name = fecha    value = factura["IssueDate"]
Set Variable   name = vence    value = factura["DueDate"]
Set Variable   name = total    value = factura["LegalMonetaryTotal"]["PayableAmount"]["#text"]
Set Variable   name = cufe     value = factura["UUID"]["#text"]
For Each   items = factura["InvoiceLine"]   itemVariable = linea
 └─ Log   message = "Línea " + str(linea["ID"]) + ": " + str(linea["LineExtensionAmount"]["#text"])

Con la factura ficticia de las pruebas del paquete, nit = "900000001", numero = "FE-1001", total = "1785000.00" y hay dos líneas.

Solo un fragmento, directamente desde el archivo:

XML to Dictionary   path = rutaFactura   xpath = "//cac:AccountingSupplierParty"   → output: emisor
Log   message = "Emisor: " + str(emisor["Party"]["PartyTaxScheme"]["CompanyID"]["#text"])

Actividades relacionadas

• XML Query Text — un solo dato con XPath.
• XML Query All — todos los valores de un XPath.
• For Each — recorrer las listas.