Expresiones de valor (Value Expressions)

Cada lugar de un Script donde se necesita un valor (una URL, un body de petición, un valor de campo, una condición, un valor de filtro, un id de destino, etc.) adopta una de las tres formas siguientes. Solo hay dos excepciones: el pattern de Regex y la key de Cache se escriben únicamente como literales y los { /pointer } que contengan no se convierten en valores. Este documento describe esas tres formas, de dónde vienen los valores (las raíces de contexto) y las reglas de mapa de locales específicas de los datos de WEEGLOO. Todos los campos del Catálogo de statements siguen estas reglas.

Las tres formas

Las tres formas se anidan: se coloca una referencia en un operando de JsonLogic y el resultado de esa referencia se introduce a su vez en otra operación.

Posición de datos y posición de expresión: cuándo poner $

El mismo JSON se lee de forma distinta según la posición. El criterio que las separa es quién es el dueño de las claves de esa posición. Las claves de fields son los id de campo de un Content Type y las claves de Http.body son el esquema de la API remota, así que en esas posiciones cat o in deben ser nombres de campo, no operadores.

La regla cabe en dos líneas.

1. En una posición de datos, una clave sin $ es siempre un nombre de campo. Para usar una operación, anteponga $ al operador.
2. Una vez que se entra en una expresión con $, todo lo de dentro es expresión. Los operadores anidados no necesitan $ (aunque se puede poner).

Si tiene dudas, anteponga $ a todos los operadores. Es correcto en cualquier posición.

// posición de datos: cat es un nombre de campo del Content Type (no la operación de concatenación)
"fields": { "cat": { "en-US": "hello" } }
 
// cálculo en una posición de datos: $ solo en la frontera; dentro, tal cual
"fields": { "tier": { "en-US": { "$if": [ { ">=": [ "{ /p/score }", 700 ] }, "gold", "silver" ] } } }
 
// posición de expresión: se escribe tal cual
"condition": { "and": [ { "<": [ "{ /a/body/risk }", 0.5 ] }, { ">=": [ "{ /b/body/score }", 700 ] } ] }

Cuando se necesita un nombre de campo que empiece por $: $$

Cuando la clave debe empezar realmente por $, como el $ref o el $schema de JSON Schema, se escribe $ dos veces. "$$ref" significa la clave de datos $ref. Solo se quita un $ inicial ($$$ref es $$ref) y se aplica solo a las claves (el $ dentro de un valor se queda tal cual).

"body": { "$$ref": "#/components/schemas/Item", "topK": { "$min": [ "{ /payload/fields/k }", 50 ] } }

Los dos casos que se rechazan

Los dos casos siguientes no se interpretan en silencio con otro significado, sino que se rechazan como error.

• Una clave $ junto a otras claves del mismo objeto es un error. La operación debe ser la única clave de ese objeto; los datos hermanos se sacan un nivel hacia fuera.
• Una clave $ desconocida es un error. $catt no es un campo llamado $catt. El espacio de nombres $ está reservado para los operadores.

En una posición de expresión también es un error que un nombre de operador conviva con claves hermanas ({ "and": […], "or": […] }). En esa posición no existe la lectura como datos y todo objeto se evalúa como verdadero, así que dejarlo así haría que la condición fuera siempre verdadera en silencio.

Referencia: { /json-pointer }

Dentro de las llaves se coloca un JSON Pointer de RFC 6901 (que debe empezar por /). Se permiten espacios en blanco alrededor de las llaves ({ /a/b } es igual que {/a/b}).

Pointer único frente a plantilla mixta: reglas de tipo

• Cuando toda la cadena es un único pointer, el valor conserva su tipo original (si es número, número; si es objeto, objeto; si es array, array).
• Cuando se mezcla con texto literal, el resultado es concatenación de cadenas (concatenation).

"{ /payload/fields/count }"                 // si es un valor numérico, número tal cual (p. ej. 42)
"{ /payload/fields/tags }"                  // si es un array, array tal cual
"page-{ /payload/fields/n }-of-10"          // concatenación de cadenas → "page-42-of-10"
"Bearer { /payload/fields/token }"          // concatenación de cadenas → "Bearer abc123"

Valores ausentes

• Cuando la ruta no existe o el valor está vacío, un pointer único se convierte en null y una plantilla mixta se convierte en una cadena vacía.

Raíces de contexto: de dónde vienen los valores

El segmento de nivel superior de un { /pointer } es uno de los siete siguientes.

Los seis nombres que quedan al descontar /<name> (payload, rawPayload, headers, now, vars, error) están reservados y no se pueden usar como name de un statement. Usar uno de ellos sobrescribiría esa raíz, así que se rechaza en el momento de guardar (reglas del nombre de vinculación en los campos comunes).

/rawPayload: el cuerpo tal cual se envió

/payload es el valor parseado y /rawPayload es la cadena original de ese mismo cuerpo. Ambos apuntan a lo mismo, pero no son iguales. Al volver a convertir en cadena el valor parseado, los espacios en blanco, la notación de los números, los escapes y las claves duplicadas quedan normalizados, y ya no se recuperan los bytes enviados.

Por eso, un valor que se calcula sobre los bytes enviados solo se puede tratar con /rawPayload. El caso representativo es la verificación de la firma del webhook de una pasarela de pago (Signature). Las referencias habituales, cuando lo que se quiere es extraer un valor, se hacen con /payload.

El cuerpo de la llamada solo admite objetos JSON. Si el cuerpo viene vacío, se considera que no hay cuerpo; si no es un objeto JSON (JSON malformado, un array, un escalar o un null literal), no se ejecuta y se rechaza (véase Errores).

/now: el instante en que arrancó la ejecución

/now contiene el instante en que arrancó esta ejecución en tres formas.

• Una ejecución tiene un único instante. No es un statement que lea el reloj, sino un valor que se fija al arrancar la ejecución, así que dos statements nunca verán valores distintos. Cada rama de un Parallel también hereda ese mismo instante. Al no ser un statement, tampoco cuenta para el número de statements.
• No hay ningún campo para elegir la zona horaria. Los valores de epoch son el mismo número en cualquier parte, e iso está en notación UTC.
• Se usa para verificar la replay window de un webhook (cuántos segundos hace, respecto a ahora, que se emitió la marca de tiempo incluida en la firma). La marca de tiempo suele llegar como cadena, pero las operaciones aritméticas la convierten en número, así que se compara tal cual.

// ¿La marca de tiempo incluida en la firma está dentro de 5 minutos (300 segundos)?
{ "<": [ { "-": [ "{ /now/seconds }", "{ /sig/1 }" ] }, 300 ] }

La forma del resultado de un statement

La forma del resultado de un statement que lleva un name varía según el tipo.

• ResourceFind vincula null cuando no hay coincidencia. Ramifique según la existencia con { "==": [ "{ /found }", null ] }.
• ResourceRead (individual) es un error cuando el destino no existe (se puede gestionar con Try). Se explica en detalle en Lectura de recursos en el Catálogo de Statements.
• Al leer un ServiceUser, el resultado es el recurso de miembro en sí ({ /member/sys/id }). A diferencia de Content y Media, sus campos no son un mapa de locales, sino el valor tal cual. Las reglas se tratan en Lectura del directorio de miembros.

Operaciones y condiciones: JsonLogic

Cuando necesite un cálculo o una condición, use un objeto de operador de la especificación de jsonlogic.com.

• El acceso a los datos se unifica con referencias { /ptr }, no con el var vanilla (dot-path). El motor resuelve primero los pointers de los operandos y luego aplica el operador.
• El operador debe ser la única clave de ese objeto. En una posición de datos, solo las claves con $ son operaciones; en una posición de expresión, son operaciones haya o no $ (véase Posición de datos y posición de expresión).

Tabla de operadores

Los nombres de la tabla son tokens de operador. Al usarlos en una posición de datos se les antepone $ (cat pasa a ser $cat). En una posición de expresión valen los dos.

Los operadores de iteración de arrays (map, filter, reduce, all, some, none) no se admiten. Script recorre los arrays con Loop (Loop en el Catálogo de Statements). Seleccionar de una lista solo los elementos que cumplen una condición de fecha tampoco es cosa del recorrido, sino de los statements de lectura. Si se da la condición en el where de ResourceFind y de ResourceForEach, el servidor filtra y devuelve el resultado (los operadores que se pueden usar están en la lista de operadores).

Conversión numérica y ejemplos

Las reglas de conversión numérica son las siguientes. Un número se deja tal cual, true se convierte en 1, false en 0, una cadena se parsea (si no se puede parsear, el cálculo falla) y null se convierte en 0.

Una cadena de fecha no es un número. "2026-10-03" no se parsea como número, así que los operadores de comparación devuelven siempre false sin dar ningún error. Para comparar fechas, normalícelas primero con date.

Los fragmentos siguientes se escriben para una posición de expresión. Al colocarlos en una posición de datos (fields, Http.body, Return.value, SetVar.value), anteponga $ al operador de nivel superior y deje los operandos internos tal cual.

{ "-":  [ "{ /wallet/fields/balance/en-US }", "{ /payload/fields/cost }" ] }   // saldo - coste
{ "<":  [ "{ /wallet/fields/balance/en-US }", "{ /payload/fields/cost }" ] }   // saldo < coste → boolean
{ "and": [ { "<": [ "{ /a/body/risk }", 0.5 ] }, { ">=": [ "{ /b/body/score }", 700 ] } ] }
{ "cat": [ "id-", "{ /payload/sys/id }" ] }                                    // "id-<uuid>"
{ "!!": "{ /found/sys/id }" }                                                  // true si existe
{ "$merge": [ "{ /vars/ids }", [ "{ /row/sys/id }" ] ] }                       // acumulación en array: SetVar.value es posición de datos, de ahí el $
{ "if": [ "{ /payload/fields/next }", "{ /payload/fields/next }", "END" ] }     // next si existe, si no "END"

Normalización de fechas (date)

Los operadores de comparación convierten los operandos en números y luego los comparan. Una cadena de fecha no es un número, así que esa comparación siempre da false sin dar ningún error. Cambiar a == tampoco lo resuelve. Cuando ninguno de los dos lados es un número se compara el texto tal cual, así que "2026-10-03" y "2026-10-03T00:00:00.000Z", que escriben el mismo instante de forma distinta, resultan valores diferentes. Las fechas se normalizan con date antes de compararlas.

{ "date": [ valor, unidad de salida ] }  // la unidad de salida se puede omitir
{ "date": "2026-10-03" }                 // si solo se pasa un valor, se puede quitar el array

No hay operadores dedicados before, after ni equal. El valor normalizado es un número, así que basta con usar tal cual los operadores de comparación, aritmética y agregación que ya existen.

El resultado de la aritmética vuelve a ser un número en milisegundos, así que se puede pasar otra vez por date para obtenerlo como iso o como day (la fila «Una semana después» de la tabla anterior).

// posición de expresión: ¿el cupón está dentro de su periodo de validez? Las notaciones de los tres valores pueden ser distintas entre sí
{ "<=": [
  { "date": "{ /coupon/fields/startsAt/en-US }" },
  { "date": "{ /now/iso }" },
  { "date": "{ /coupon/fields/endsAt/en-US }" }
] }
 
// posición de expresión: ¿el header Date de HTTP está dentro de 5 minutos (300 segundos) respecto a ahora?
{ "<": [ { "-": [ "{ /now/seconds }", { "date": [ "{ /headers/date }", "seconds" ] } ] }, 300 ] }

Entradas que se leen

Todos los valores siguientes se leen como el mismo instante.

• Si no hay offset, se lee como UTC. Como offset se admiten +09:00, +0900, +09 y Z.
• El parseo es estricto. Aunque el número de dígitos cuadre, una fecha que no existe realmente (2026-13-45) falla.
• En un epoch, la unidad se distingue por la magnitud del valor absoluto. Por debajo de 100.000.000.000 son segundos y a partir de ahí, milisegundos. Por eso, tanto { /now/seconds } como { /now/millis } se leen correctamente, cada uno en su unidad.
• El rango que se acepta como epoch es un valor absoluto igual o mayor que 100.000.000 y menor que 100.000.000.000.000. Como la unidad hay que distinguirla por la magnitud, el rango queda acotado por los dos lados. Un número que quede fuera falla en lugar de leerse como el año 1970. Es el caso de una fecha sin separadores como 20261003, de un año como 2026 y del 0 que llega con el significado de que no hay valor.

Unidad de salida

El segundo operando decide la forma de la salida. El nombre de la unidad no distingue entre mayúsculas y minúsculas.

Si se da un nombre que no está en la lista, falla, y el mensaje de error enumera los nombres que se pueden usar.

La salida iso y la escritura en un campo Date

Para escribir, el campo Date de un Content solo admite un formato: yyyy-MM-ddTHH:mm:ss[.fracción]Z. Tienen que estar la T, los segundos y la Z final, las fracciones de segundo se pueden poner o quitar, y el valor se lee como UTC. Por eso, si se escribe tal cual un 2026-10-03 o un 2026-10-03T09:00:00+09:00 recibido en el payload, se rechaza porque el valor no es válido. La salida iso de date es exactamente ese formato, así que la fecha recibida se pasa una vez por date antes de escribirla en el campo.

// posición de datos: escribe el "2026-10-03" del payload en la fecha de caducidad del cupón
"fields": { "endsAt": { "en-US": { "$date": [ "{ /payload/fields/endsAt }", "iso" ] } } }

Valores que no se pueden leer

En los tres casos siguientes, ese statement falla (status 400). Al ser un fallo que se produce durante la ejecución, se puede tratar de forma local con el catch de Try.

• El primer operando no está, o la referencia no ha encontrado ningún valor.
• El valor no se puede leer como fecha. Es el caso de una cadena vacía, una cadena con solo espacios en blanco, una cadena que no es una fecha, una fecha que no existe, un booleano, un objeto y un número fuera del rango aceptado.
• El nombre de la unidad de salida no está en la lista.

No devolver null cuando no hay valor es un contrato deliberado. En la conversión numérica, null pasa a ser 0 y se compara contra el año 1970, así que una comprobación a la que le falta la fecha no falla: lo que hace es invertir el resultado. Es peor que un cupón fuera de su periodo de validez pase la comprobación que detener la ejecución.

Evaluación de verdadero y falso (Truthiness)

if, and, or, !, !!, junto con If.condition y Loop.while, determinan verdadero y falso según las reglas siguientes.

• falsy: null, false, el número 0, la cadena vacía "", una colección vacía (un array vacío).
• truthy: todo lo demás (números distintos de 0, cadenas y arrays no vacíos, y todos los objetos).

Las claves también pueden ser referencias

Las claves de un mapa como fields también admiten referencias { /ptr }. La clave se resuelve en tiempo de ejecución.

"fields": { "{ /payload/fields/fieldName }": { "en-US": "{ /payload/fields/fieldValue }" } }

Si dos claves se resuelven al mismo valor, colisionan y es un error del motor.

Mapa de locales: reglas específicas de Content y Media

En WEEGLOO, cada campo de un Content o Media no es un valor sino un mapa por locale (por ejemplo, balance es { "en-US": 1, "ko-KR": 10 }). Por eso, al leer y escribir hay que gestionar el locale de forma conjunta. En Media también, title y description (escalares) y file (la instrucción de ingesta) son mapas de locales. El JSON que no es Content ni Media, como /payload o una respuesta HTTP, no se ve afectado por esta regla (mantiene la estructura que define el esquema, y un escalar sigue siendo un escalar).

Lectura

• Para obtener un escalar, especifique hasta el locale: { /<name>/fields/<field>/<locale> } (por ejemplo, { /post/fields/title/en-US }).
• Sin locale, { /<name>/fields/<field> } devuelve el objeto completo del mapa de locales.
• Un campo localized:false está solo en el bucket del locale predeterminado, así que se lee con el código de ese locale predeterminado.

Escritura (los fields de ResourceCreate, ResourceUpdate, ResourcePatch)

El valor es un mapa de locales, { "<locale>": <expresión de valor escalar> }. Es simétrico con la lectura.

"fields": {
  "title":  { "en-US": "Hello", "ko-KR": "안녕" },   // enumera buckets para varios locales
  "status": { "en-US": "paid" }
}

• ResourceCreate debe incluir el bucket del locale predeterminado del Space en cada campo que rellena (la regla default-locale).
• ResourceUpdate es un reemplazo completo. Los campos y locales que no estén en fields se eliminan (incluido el archivo).
• ResourcePatch actualiza solo los campos y buckets especificados (los demás campos y locales se mantienen).
• Eliminación con un null literal: cuando el valor es un null literal, se elimina ese bucket (field, locale) (la forma estándar de vaciar un locale concreto en un Patch). "" (una cadena vacía) no es una eliminación, sino que establece un valor vacío. Cuando una expresión de valor ({ /ptr }) se evalúa como null en tiempo de ejecución, no es una eliminación sino un error (un payload ausente no se traga en silencio). Solo un null literal elimina.
• Media file: el valor no es un escalar sino una instrucción de ingesta, { "source": …, "encoding": "url"|"base64" }. Lo que hace realmente la ingesta se trata en ResourceCreate en el Catálogo de Statements.
• Un campo localized:false se coloca solo en el bucket del locale predeterminado.
• El código de locale (la clave del mapa) también puede ser una referencia { /ptr } (véase arriba Las claves también pueden ser referencias). Se usa para crear locales dinámicos.

Campo de conveniencia locale

Si se da locale a ResourceCreate, ResourceUpdate o ResourcePatch, el motor envuelve automáticamente cada valor de fields en un bucket { <locale>: valor }. Es decir, basta con dar escalares.

// los dos siguientes son equivalentes
{ "type": "ResourceCreate", "resource": "Content", "contentType": { "sys": { "id": "ct_post" } },
  "locale": "en-US", "fields": { "title": "Hello" } }
 
{ "type": "ResourceCreate", "resource": "Content", "contentType": { "sys": { "id": "ct_post" } },
  "fields": { "title": { "en-US": "Hello" } } }

Si se da locale y el valor ya anida un mapa de locales ({ "en-US": … }), se produce un anidamiento doble como { <locale>: { "en-US": … } } (error del autor). Unifique en un solo estilo: con locale, solo escalares; sin él, solo mapas de locales explícitos.

El locale en where y order

• En where y order, para fields.X el motor aplica automáticamente el locale predeterminado del Space (igual que una consulta de CMA).
• Para indicar un locale específico, especifíquelo como fields.X.<locale>.

"where": { "fields.slug": { "eq": "{ /payload/fields/slug }" } }   // slug del locale predeterminado
"where": { "fields.title.ko-KR": { "prefix": "안" } }              // locale específico

Errores

Códigos que aparecen cuando se incumplen las reglas de las expresiones de valor. Se comprueban al guardar; los códigos por incumplir las demás restricciones estáticas de la definición están en los errores de Semántica de ejecución, restricciones y seguridad, y los códigos que aparecen al invocar, en los errores de los endpoints. Para los códigos comunes a todos los recursos, consulte Errores comunes.

Documentos relacionados

• Catálogo de statements: Los campos y resultados de los 25 tipos de statement que usan expresiones de valor.
• Semántica de ejecución, restricciones y seguridad: Orden de ejecución, errores, bloqueo optimista y restricciones estáticas.
• Cookbook: Ejemplos completos que combinan expresiones de valor.
• Descripción general de Script: La estructura de nivel superior y el tiempo que recibe una ejecución.