# serialize.dkh `serialize.dkh` convierte datos de DKL a texto y de regreso: - **JSON**: `to.json`, `to.jsonNet` y `from.json`, para servicios web, archivos de configuración y llamadas a API; - **XML y DKL**: `parse.xmlStr`, `parse.xmlFile`, `parse.dklStr` y `parse.dklFile` convierten un documento en un árbol de registros que se recorre y modifica en modo imperativo, y `to.xml` lo vuelve a convertir en XML. Sus funciones están en `Devkron.Serialize.dll`. En Devkron 2.0 el serializador JSON es propio (ya no usa fastJSON) y produce **exactamente la misma salida** que 1.x. ```dkl #include "dkli.dkh" #! program "servicio" { #include "functions.dkh" #include "serialize.dkh" new datos { @"ok": 1 } do print(to.json(datos)) } ``` ```text {"ok":1} ``` ## JSON | Función | Devuelve | Qué hace | |---|---|---| | `to.json(objeto)` | Cadena | Serializa un registro, una lista, una tabla o un valor a JSON | | `to.jsonNet(objeto, extensiones)` | Cadena | Igual, y con `extensiones` = `@true` agrega información de tipos .NET (`$types`, `$type`, `$schema`) a los objetos .NET y a las tablas. Con `@false` es igual a `to.json` | | `from.json(cadena)` | Referencia | Convierte JSON en un registro (objeto) o una lista (arreglo); use `ref` | Cómo se convierte cada tipo al escribir con `to.json`: | En DKL | En JSON | |---|---| | Registro | Objeto `{…}` | | Lista | Arreglo `[…]` | | Tabla | `{"NombreTabla": [[fila], [fila]]}` (arreglo de filas, cada fila arreglo de valores) | | Cadena | Cadena con escapes; los caracteres no ASCII se escriben como `\u00E9` | | Número | Número con punto decimal | | `@true` / `@false` | `1` / `0` (son números en DKL) | | Nulo | `null` | | Fecha | Cadena ISO 8601 **en UTC**: `"2026-10-27T09:30:00Z"` (se convierte desde la hora local del servidor) | | Otro objeto .NET | `{}` con sus propiedades públicas legibles, o vacío | Al leer con `from.json`: los objetos se vuelven registros, los arreglos listas, los números quedan como números, `true`/`false` como booleanos y `null` como nulo (el campo existe, pero vale nulo). ```dkl #include "dkli.dkh" #! program "ser" { #include "functions.dkh" #include "serialize.dkh" new pedido { @"folio": "A-100" @"total": 300.5 @"pagado": @true @"nota": "Envío \"express\"" } ref partidas = list.create() new p1 { @"sku": "P-01" @"cantidad": 2 } do list.add(partidas, p1) pedido<"partidas*">: partidas pedido<"cliente*">: @null ref fecha = str2dt("2026-10-27 09:30:00") pedido<"fecha*">: fecha texto = to.json(pedido) do print(texto) ref leido = from.json(texto) do print(field.str(leido, "folio") + " " + str(field.num(leido, "total") + 1)) ref pl = field.obj(leido, "partidas") ref pp = list.obj(pl, 0) do print(field.str(pp, "sku")) do print(field.exist(leido, "cliente")) do print(isnull(field.dobj(leido, "cliente", @null))) do print(field.str(leido, "fecha")) ref arr = from.json("[1, \"dos\", {\"tres\": 3}, null, true]") do print(list.count(arr)) do print(to.json(arr)) ref malo = from.json("{\"a\": ") exception { do print(last_error()) do clear_exceptions() } } ``` ```text {"folio":"A-100","total":300.5,"pagado":1,"nota":"Env\u00EDo \"express\"","partidas":[{"sku":"P-01","cantidad":2}],"cliente":null,"fecha":"2026-10-27T09:30:00Z"} A-100 301.5 P-01 1 1 2026-10-27T09:30:00Z 5 [1,"dos",{"tres":3},null,true] {1} Error en 'from.json. (Reached end of string unexpectedlyException has been thrown by the target of an invocation.) [ser.dkl][Ln= 38] ``` Notas: - La fecha del ejemplo se serializó en UTC (ejecutado con `TZ=UTC`); en un servidor con zona `America/Mexico_City` la misma fecha local sale como `"2026-10-27T15:30:00Z"`. `from.json` **no** convierte esa cadena de vuelta a fecha: queda como texto. Para manejar fechas en JSON sin sorpresas, guárdelas como texto con `date_str(f, "yyyy-MM-dd HH:mm:ss")`. - Para leer un campo dentro de una lista use `field.obj` y `list.obj`; una ruta `"partidas/0/cantidad"` da `No es un record`. - Un registro que se contiene a sí mismo, o un anidamiento extremo, lanza una excepción normal (`JSON: referencia circular, un objeto se contiene a sí mismo`) que se captura con `exception`. En 1.x abortaba el proceso. ### Información de tipos: to.jsonNet `to.jsonNet(objeto, @true)` es para intercambiar datos con programas .NET que necesitan los nombres de tipo. Sobre registros y listas de DKL da lo mismo que `to.json`; solo agrega información en objetos .NET y tablas: ```dkl #include "dkli.dkh" #! program "jnet" { #include "functions.dkh" #include "serialize.dkh" new m { @"sku": "P-01" @"n": 2 } ref t = table.create(m) do row.add(t, m) do print(to.json(t)) do print(to.jsonNet(t, @true)) ref ex = _new("System.Version", "2.0") do print(to.json(ex)) do print(to.jsonNet(ex, @true)) } ``` ```text {"Table":[["P-01",2]]} {"$schema":{"$types":{"fastJSON.DatasetSchema, fastJSON, Version=2.4.0.5, Culture=neutral, PublicKeyToken=6b75a806b86095cd":"1"},"$type":"1","Info":["Table","sku","System.String","Table","n","System.Decimal"],"Name":"Table"},"Table":[["P-01",2]]} {} {"$types":{"System.Version, System.Private.CoreLib, Version=10.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e":"1"},"$type":"1"} ``` ### Responder JSON desde un servicio web ```dkl #include "dkli.dkh" #! program "servicio" { #include "functions.dkh" #include "serialize.dkh" new datos { @"ok": 1 } @http_context<"response/headers/content-type">: "application/json;charset=utf-8" @http_context<"response/output">: "text" @http_context<"response/text">: to.json(datos) } ``` Y para leer un cuerpo JSON recibido por POST: `ref entrada = from.json(@@(@http_context, "request/body"))` (o las funciones `httpreq.*` de [http.dkh](/es/devkron/2.0/bibliotecas/estandar/http.md)). ## XML y DKL como árbol de registros `parse.xmlStr`, `parse.xmlFile`, `parse.dklStr` y `parse.dklFile` devuelven el **elemento raíz** como un registro con esta forma: | Campo | Contenido | |---|---| | `name` | Nombre del elemento (con prefijo si lo tiene: `cfdi:Emisor`) | | `type` | `"element"` | | `attributes` | Registro con los atributos (todos como cadena) | | `nodes` | Lista de nodos hijos: elementos (misma forma), textos `{"type":"text","data":"…"}` y CDATA `{"type":"cdata","data":"…"}` | | `meta` | Registro con los meta-atributos del elemento (DKL) | | Función | Qué hace | |---|---| | `parse.xmlStr(cadena)` | Árbol de un XML en una cadena | | `parse.xmlFile(archivo)` | Árbol de un archivo XML | | `parse.dklStr(cadena)` | Árbol de código DKL **declarativo** en una cadena | | `parse.dklFile(archivo)` | Árbol de un archivo DKL | | `to.xml(árbol)` | Cadena XML a partir de un árbol con esa forma (escapa `&`, `<`, `>`) | ```dkl #include "dkli.dkh" #! program "xml" { #include "functions.dkh" #include "serialize.dkh" xml = "Caféurgente]]>" ref arbol = parse.xmlStr(xml) do print(to.json(arbol)) do print(field.str(arbol, "name") + " folio=" + field.str(arbol, "attributes/folio")) ref hijos = field.obj(arbol, "nodes") ref concepto = list.obj(hijos, 0) ref texto = list.obj(field.obj(concepto, "nodes"), 0) do print(field.str(concepto, "attributes/clave") + ": " + field.str(texto, "data")) concepto<"attributes/clave">: "P-99" do print(to.xml(arbol)) do file.wtext("/tmp/dkdoc/f.xml", xml) ref a2 = parse.xmlFile("/tmp/dkdoc/f.xml") do print(field.str(a2, "attributes/total")) ref parcial = parse.xmlStr("") exception { do print(last_error()) do clear_exceptions() } using @parseSettings { member @"xml_prefixes" { @"cfdi": "http://www.sat.gob.mx/cfd/4" } } ref parcial2 = parse.xmlStr("") do print(field.str(parcial2, "name") + " " + field.str(parcial2, "attributes/Rfc")) do file.delete("/tmp/dkdoc/f.xml") } ``` ```text {"name":"factura","attributes":{"folio":"A-100","total":"300.50"},"nodes":[{"name":"concepto","attributes":{"clave":"P-01"},"nodes":[{"type":"text","data":"Caf\u00E9"}],"meta":{},"type":"element"},{"name":"nota","attributes":{},"nodes":[{"type":"cdata","data":"urgente"}],"meta":{},"type":"element"}],"meta":{},"type":"element"} factura folio=A-100 P-01: Café Caféurgente]]> 300.50 {1} Error en 'parse._xmlStr. ('cfdi' is an undeclared prefix. Line 1, position 2.Exception has been thrown by the target of an invocation.) [serialize.dkh][Ln= 34] cfdi:Emisor XAXX010101000 ``` ### Leer un fragmento con prefijos: xml_prefixes Si el XML usa prefijos sin declarar sus espacios de nombres (típico al leer una parte de un CFDI), el analizador falla con `'cfdi' is an undeclared prefix`. Declárelos en el campo `xml_prefixes` del registro global `@parseSettings` antes de llamar a `parse.xmlStr` o `parse.xmlFile`, como se ve al final del ejemplo anterior: ```dkl using @parseSettings { member @"xml_prefixes" { @"cfdi": "http://www.sat.gob.mx/cfd/4" @"tfd": "http://www.sat.gob.mx/TimbreFiscalDigital" } } ``` ### Árbol de código DKL En el texto DKL los atributos se separan con **espacios** (`opcion(id="1" texto="Ventas")`), no con comas. ```dkl #include "dkli.dkh" #! program "dklparse" { #include "functions.dkh" #include "serialize.dkh" codigo = "menu { opcion(id=\"1\" texto=\"Ventas\"){} opcion(id=\"2\" texto=\"Compras\"){ \"Texto libre\" } }" ref arbol = parse.dklStr(codigo) do print(field.str(arbol, "name")) ref ops = field.obj(arbol, "nodes") go foreach.lobj(value:o) with(ops) { do print(field.str(o, "attributes/id") + " " + field.str(o, "attributes/texto")) } do print(to.xml(arbol)) do file.wtext("/tmp/dkdoc/menu.dkl", codigo) ref a2 = parse.dklFile("/tmp/dkdoc/menu.dkl") do print(list.count(field.obj(a2, "nodes"))) do file.delete("/tmp/dkdoc/menu.dkl") @parseSettings<"nodes">: "hijos" ref a3 = parse.dklStr(codigo) do print(field.exist(a3, "hijos")) } ``` ```text menu 1 Ventas 2 Compras Texto libre 2 1 ``` ### Nombres de los campos: @parseSettings `@parseSettings` define cómo se llaman los campos del árbol (`name`, `type`, `attributes`, `nodes`, `meta`, `data`). Puede cambiarlos (como `hijos` al final del ejemplo anterior), pero hágalo **en su programa**, nunca editando `serialize.dkh`, para que una actualización de Devkron no rompa su código. El cambio afecta también a `to.xml`. ### Armar XML desde cero `to.xml` acepta cualquier registro con la forma del árbol, por ejemplo uno armado con `from.json`. Cada nodo necesita su campo `type`: ```dkl #include "dkli.dkh" #! program "xb" { #include "functions.dkh" #include "serialize.dkh" ref n = from.json("{\"type\":\"element\",\"name\":\"respuesta\",\"attributes\":{\"ok\":\"1\"},\"nodes\":[{\"type\":\"text\",\"data\":\"Listo & \"}]}") do print(to.xml(n)) ref bad = from.json("{\"name\":\"x\"}") do print(to.xml(bad)) exception { do print(last_error()) do clear_exceptions() } ref t = parse.xmlStr("") exception { do print(last_error()) do clear_exceptions() } } ``` ```text Listo & <hecho> 0 {1} Error en 'parse.buildXml. (The given key 'type' was not present in the dictionary.Exception has been thrown by the target of an invocation.) [serialize.dkh][Ln= 26] {1} Error en 'parse._xmlStr. (Data at the root level is invalid. Line 1, position 1.Exception has been thrown by the target of an invocation.) [serialize.dkh][Ln= 34] ``` ## Errores típicos | Mensaje | Causa | Solución | |---|---|---| | `Reached end of string unexpectedly` (u otro de `from.json`) | JSON incompleto o inválido | Valide el texto recibido; capture con `exception` y responda 400 | | `Función: to.json no reconocida o no registrada` | Falta `#include "serialize.dkh"` | Agréguelo dentro de `program` | | `'cfdi' is an undeclared prefix.` | Prefijo XML sin espacio de nombres | Declárelo en `@parseSettings<"xml_prefixes">` | | `Data at the root level is invalid. Line 1, position 1.` | El texto no es XML | Revise el origen (codificación, BOM, HTML de error) | | `Could not find file '…'.` en `parse._xmlFile` | El archivo no existe | Compruebe con `file.exists` | | `Se ha indicado una lista de valores de atributos por orden, pero no hay una definición del elemento` | Atributos DKL separados por comas | Sepárelos con espacios | | `The given key 'type' was not present in the dictionary.` en `to.xml` | Un nodo del árbol no tiene `type` | Agregue `"type": "element"` (o `text`, `cdata`) | | `JSON: referencia circular, un objeto se contiene a sí mismo` | Un registro se contiene a sí mismo | Quite la referencia circular antes de serializar | ## Relación con la documentación 1.x | Página 1.x | En esta página | |---|---| | [serialize.dkh](/es/devkron/Bibliotecas-de-funciones/serialize/serialize.md) | Toda la página | | [to.json](/es/devkron/Bibliotecas-de-funciones/serialize/serializacion_deserializacion/to.json.md), [from.json](/es/devkron/Bibliotecas-de-funciones/serialize/serializacion_deserializacion/from.json.md), [to.jsonNet](/es/devkron/Bibliotecas-de-funciones/serialize/serializacion_deserializacion/to.jsonNet.md) | JSON | | [parse.xmlStr](/es/devkron/Bibliotecas-de-funciones/serialize/funcion_deserializacion/parse.xmlStr.md), [parse.xmlFile](/es/devkron/Bibliotecas-de-funciones/serialize/funcion_deserializacion/parse.xmlFile.md), [parse.dklStr](/es/devkron/Bibliotecas-de-funciones/serialize/funcion_deserializacion/parse.dklStr.md), [parse.dklFile](/es/devkron/Bibliotecas-de-funciones/serialize/funcion_deserializacion/parse.dklFile.md) | XML y DKL como árbol de registros | > En la 1.x, `to.jsonNet` aparecía con un solo argumento y `to.xml` como `to.Xml`; los nombres y firmas correctos son `to.jsonNet(objeto, extensiones)` y `to.xml(árbol)` (los nombres de función no distinguen mayúsculas, así que `to.Xml` también funciona). [Regresar a Bibliotecas del motor](/es/devkron/2.0/bibliotecas/motor/)