# 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
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/)