Expressões de valor (Value Expressions)

Todo lugar em um Script onde é necessário um valor (uma URL, um corpo de requisição, um valor de campo, uma condição, um valor de filtro, um id de destino, etc.) assume uma das três formas abaixo. As exceções são apenas duas: o pattern de Regex e a key de Cache são usados somente como literais, e um { /pointer } dentro deles não é convertido em valor. Este documento descreve essas três formas, de onde vêm os valores (as raízes de contexto) e as regras de mapa de locales específicas dos dados do WEEGLOO. Todos os campos do Catálogo de statements seguem essas regras.

As três formas

As três formas se aninham: você coloca uma referência em um operando de JsonLogic e reintroduz o resultado dessa referência em outra operação.

Posição de dados e posição de expressão: quando usar $

O mesmo JSON é lido de maneiras diferentes conforme a posição. O critério que separa os casos é quem é o dono das chaves daquela posição. As chaves de fields são ids de campo de um Content Type e as chaves de Http.body são o esquema da API do outro lado; por isso, nessas posições, cat ou in devem ser nomes de campo, e não operadores.

A regra cabe em duas linhas.

1. Em uma posição de dados, uma chave sem $ é sempre um nome de campo. Para usar uma operação, acrescente $ ao operador.
2. Uma vez que o $ leva para dentro de uma expressão, tudo o que está lá dentro é expressão. Os operadores aninhados não precisam de $ (mas podem tê-lo).

Na dúvida, acrescente $ a todos os operadores. Isso vale em qualquer posição.

// posição de dados: cat é o nome de um campo do Content Type (não é a operação de concatenação)
"fields": { "cat": { "en-US": "hello" } }
 
// cálculo em uma posição de dados: $ só na fronteira, o interior fica como está
"fields": { "tier": { "en-US": { "$if": [ { ">=": [ "{ /p/score }", 700 ] }, "gold", "silver" ] } } }
 
// posição de expressão: escreve-se tal como está
"condition": { "and": [ { "<": [ "{ /a/body/risk }", 0.5 ] }, { ">=": [ "{ /b/body/score }", 700 ] } ] }

Quando o nome de um campo precisa começar com $: $$

Quando a chave realmente precisa começar com $, como acontece com $ref e $schema do JSON Schema, escreva $ duas vezes. "$$ref" significa a chave de dados $ref. Apenas um $ do início é removido ($$$ref vira $$ref), e isso se aplica somente às chaves (o $ dentro de um valor fica como está).

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

Os dois casos rejeitados

Os dois casos abaixo não são interpretados silenciosamente com outro sentido, e sim rejeitados como erro.

• Uma chave $ junto com outras chaves no mesmo objeto é um erro. A operação precisa ser a única chave desse objeto, e basta mover os dados irmãos um nível para fora.
• Uma chave $ desconhecida é um erro. $catt não é um campo chamado $catt. O namespace $ é reservado para os operadores.

Em uma posição de expressão, também é um erro que o nome de um operador apareça junto com chaves irmãs ({ "and": […], "or": […] }). Nessa posição não existe a interpretação como dados e todo objeto é avaliado como verdadeiro, portanto, se ficasse assim, a condição passaria a ser silenciosamente sempre verdadeira.

Referência: { /json-pointer }

Coloque um JSON Pointer conforme a RFC 6901 (que deve começar com /) dentro das chaves. Espaços em branco ao redor das chaves são permitidos ({ /a/b } é igual a {/a/b}).

Pointer único vs. template misto: regras de tipo

• Quando toda a string é um único pointer, o valor mantém seu tipo original (se for número, número; se for objeto, objeto; se for array, array).
• Quando é misturado com texto literal, o resultado é concatenação de strings (concatenation).

"{ /payload/fields/count }"                 // se for um valor numérico, número tal como está (ex.: 42)
"{ /payload/fields/tags }"                  // se for um array, array tal como está
"page-{ /payload/fields/n }-of-10"          // concatenação de strings → "page-42-of-10"
"Bearer { /payload/fields/token }"          // concatenação de strings → "Bearer abc123"

Valores ausentes

• Quando o caminho não existe ou o valor está vazio, um único pointer se torna null e um template misto se torna uma string vazia.

Raízes de contexto: de onde vêm os valores

O segmento de nível superior de um { /pointer } é um dos sete a seguir.

Os seis nomes fora de /<name> (payload·rawPayload·headers·now·vars·error) são reservados e não podem ser usados como name de um statement. Usar o mesmo nome sobrescreveria aquela raiz, por isso é rejeitado no momento do salvamento (veja Regras de nome de vínculo, nos campos comuns).

/rawPayload: o corpo exatamente como foi enviado

/payload é o valor parseado; /rawPayload é a string original do mesmo corpo. Os dois apontam para a mesma coisa, mas não são a mesma coisa. Transformar de novo em string o valor parseado normaliza espaços, notação numérica, escapes e chaves duplicadas, e não devolve os bytes enviados.

Por isso, um valor calculado sobre os bytes enviados só pode ser tratado com /rawPayload. O caso mais representativo é a verificação de assinatura de um webhook de processadora de pagamentos (veja Signature). Para a referência comum, de extrair e usar valores, use /payload.

O corpo da chamada aceita apenas um objeto JSON. Um corpo vazio é tratado como ausente e, se não for um objeto JSON (JSON malformado, array, escalar, null literal), a execução não ocorre e a requisição é rejeitada (consulte Erros).

/now: o instante em que a execução começou

/now guarda o instante em que esta execução começou, em três formas.

• Uma execução tem um único instante. Não é um statement que lê o relógio, mas um valor plantado no início da execução, portanto não há como dois statements verem valores diferentes. Cada branch de um Parallel também herda o mesmo instante. E, por não ser um statement, ele não conta no número de statements.
• Não existe campo para escolher o fuso horário. Os valores de epoch são o mesmo número em qualquer lugar, e iso é uma notação UTC.
• Use-o para verificar a janela de replay de um webhook (se o timestamp que acompanha a assinatura está a poucos segundos de agora). O timestamp normalmente chega como string, mas as operações aritméticas o convertem em número, portanto compare-o tal como está.

// o timestamp que acompanha a assinatura está dentro de 5 minutos (300 segundos)?
{ "<": [ { "-": [ "{ /now/seconds }", "{ /sig/1 }" ] }, 300 ] }

A forma do resultado de um statement

A forma do resultado de um statement que carrega um name varia conforme o tipo.

• ResourceFind vincula null quando não há correspondência. Faça a ramificação por existência com { "==": [ "{ /found }", null ] }.
• ResourceRead (individual) é um erro quando o alvo não existe (é possível tratá-lo com Try). Os detalhes são abordados em Leitura de recursos no Catálogo de statements.
• Quando você lê um ServiceUser, o resultado é o próprio recurso do membro ({ /member/sys/id }). Diferente de Content e Media, os campos dele não são mapas de locale, mas os valores diretamente. As regras são abordadas em Leitura do diretório de membros.

Operações e condições: JsonLogic

Quando precisar de um cálculo ou uma condição, use um objeto operador da especificação de jsonlogic.com.

• O acesso aos dados é unificado em referências { /ptr }, não no var vanilla (dot-path). O motor resolve primeiro os pointers dos operandos e depois aplica o operador.
• O operador precisa ser a única chave desse objeto. Em uma posição de dados, só uma chave com $ é uma operação; em uma posição de expressão, é uma operação com ou sem $ (veja Posição de dados e posição de expressão).

Tabela de operadores

Os nomes da tabela são tokens de operador. Ao usá-los em uma posição de dados, coloque $ na frente (cat vira $cat). Em uma posição de expressão, as duas formas funcionam.

Os operadores de iteração de arrays (map, filter, reduce, all, some, none) não são suportados. O Script percorre um array com Loop (Loop no Catálogo de statements). Selecionar de uma lista apenas os itens que atendem a uma condição de data também não é iteração, e sim tarefa dos statements de leitura. Dê a condição no where de ResourceFind e de ResourceForEach, e o servidor filtra e devolve o resultado (os operadores que podem ser usados estão na lista de operadores).

Conversão numérica e exemplos

As regras de conversão numérica são as seguintes. Um número é mantido como está, true vira 1, false vira 0, uma string é parseada (se não puder ser parseada, o cálculo falha) e null vira 0.

Uma string de data não é um número. "2026-10-03" não é parseada como número, portanto os operadores de comparação devolvem sempre false, sem erro. Para comparar datas, normalize-as primeiro com date.

Os trechos abaixo têm como referência uma posição de expressão. Ao colocá-los em uma posição de dados (fields, Http.body, Return.value, SetVar.value), acrescente $ ao operador de nível superior e deixe os operandos internos como estão.

{ "-":  [ "{ /wallet/fields/balance/en-US }", "{ /payload/fields/cost }" ] }   // saldo - custo
{ "<":  [ "{ /wallet/fields/balance/en-US }", "{ /payload/fields/cost }" ] }   // saldo < custo → boolean
{ "and": [ { "<": [ "{ /a/body/risk }", 0.5 ] }, { ">=": [ "{ /b/body/score }", 700 ] } ] }
{ "cat": [ "id-", "{ /payload/sys/id }" ] }                                    // "id-<uuid>"
{ "!!": "{ /found/sys/id }" }                                                  // true se existir
{ "$merge": [ "{ /vars/ids }", [ "{ /row/sys/id }" ] ] }                       // acumulação em array: SetVar.value é posição de dados, por isso o $
{ "if": [ "{ /payload/fields/next }", "{ /payload/fields/next }", "END" ] }     // next se existir, caso contrário "END"

Normalização de datas (date)

Os operadores de comparação convertem os operandos em número e só então os comparam. Uma string de data não é um número, portanto essa comparação resulta sempre em false, sem erro. Trocar o operador por == não resolve. Quando nenhum dos dois lados é um número, o texto é comparado diretamente, e assim "2026-10-03" e "2026-10-03T00:00:00.000Z", que escrevem o mesmo instante de formas diferentes, passam a ser dois valores distintos. Normalize a data com date antes de compará-la.

{ "date": [ valor, unidade de saída ] }   // a unidade de saída pode ser omitida
{ "date": "2026-10-03" }                  // ao passar um único valor, o array pode ser dispensado

Não existem operadores dedicados before, after ou equal. Como o valor normalizado é um número, basta usar os operadores de comparação, aritmética e agregação que já existem.

O resultado da aritmética é de novo um número em milissegundos, portanto você pode passá-lo mais uma vez por date para produzir a saída em iso ou day (veja "Uma semana depois" na tabela acima).

// posição de expressão: o cupom está dentro do período de validade? Os três valores podem estar em notações diferentes
{ "<=": [
  { "date": "{ /coupon/fields/startsAt/en-US }" },
  { "date": "{ /now/iso }" },
  { "date": "{ /coupon/fields/endsAt/en-US }" }
] }
 
// posição de expressão: o cabeçalho HTTP Date está dentro de 5 minutos (300 segundos) a partir de agora?
{ "<": [ { "-": [ "{ /now/seconds }", { "date": [ "{ /headers/date }", "seconds" ] } ] }, 300 ] }

As entradas que são lidas

Todos os valores abaixo são lidos como o mesmo instante.

• Sem offset, o valor é lido como UTC. Como offset são aceitos +09:00, +0900, +09 e Z.
• O parse é estrito. Mesmo com a quantidade certa de dígitos, uma data que de fato não existe (2026-13-45) falha.
• No epoch, a magnitude do valor absoluto decide a unidade. Abaixo de 100.000.000.000 são segundos; a partir desse valor, milissegundos. Por isso, tanto { /now/seconds } quanto { /now/millis } são lidos corretamente, qualquer que seja o que você passe.
• A faixa aceita como epoch é um valor absoluto de 100.000.000 até menos de 100.000.000.000.000. Como a unidade precisa ser decidida pela magnitude, a faixa é limitada nos dois lados. Os outros números falham em vez de serem lidos como o ano 1970. É o caso da data sem separadores 20261003, do ano 2026 e do 0 que é passado com o sentido de valor ausente.

A unidade de saída

O segundo operando define a forma da saída. Os nomes das unidades não diferenciam maiúsculas de minúsculas.

Um nome que não está na lista faz a operação falhar, e a mensagem de erro enumera os nomes que podem ser usados.

A saída iso e a escrita em um campo Date

Um campo Date de Content aceita, na escrita, apenas um formato: yyyy-MM-ddTHH:mm:ss[.fração]Z. O T, os segundos e o Z do final precisam estar todos presentes, a fração de segundo pode entrar ou não, e o valor é lido como UTC. Por isso, colocar tal como está um 2026-10-03 ou um 2026-10-03T09:00:00+09:00 recebido pelo payload faz com que ele seja rejeitado como valor inválido. Como a saída iso de date é exatamente esse formato, passe a data recebida uma vez por date antes de escrevê-la no campo.

// posição de dados: o "2026-10-03" do payload é escrito na data de expiração do cupom
"fields": { "endsAt": { "en-US": { "$date": [ "{ /payload/fields/endsAt }", "iso" ] } } }

Valores que não podem ser lidos

Nos três casos abaixo, aquele statement falha (status 400). É uma falha que ocorre durante a execução, portanto pode ser tratada localmente com o catch de Try.

• O primeiro operando está ausente, ou a referência não encontrou um valor.
• O valor não pode ser lido como data. É o caso de uma string vazia, de uma string só com espaços, de uma string que não é uma data, de uma data que não existe, de um booleano, de um objeto e de um número fora da faixa aceita.
• O nome da unidade de saída não está na lista.

Não devolver null quando o valor está ausente é um contrato intencional. Na conversão numérica, null vira 0 e passa a ser comparado com o ano 1970, portanto uma verificação sem a data não falha: o resultado se inverte. Um cupom fora do período de validade passando é pior do que a execução parar.

Avaliação de verdadeiro e falso (Truthiness)

if, and, or, !, !!, junto com If.condition e Loop.while, determinam verdadeiro e falso pelas regras a seguir.

• falsy: null, false, o número 0, a string vazia "" e uma coleção vazia (um array vazio).
• truthy: todo o resto (números diferentes de 0, strings e arrays não vazios, e todos os objetos).

As chaves também podem ser referências

As chaves de um mapa como fields também suportam referências { /ptr }. A chave é resolvida em tempo de execução.

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

Se duas chaves forem resolvidas para o mesmo valor, elas colidem e é um erro do motor.

Mapa de locales: regras específicas de Content e Media

No WEEGLOO, cada campo de um Content ou Media não é um valor, mas um mapa por locale (por exemplo, balance é { "en-US": 1, "ko-KR": 10 }). Por isso, ao ler e escrever, é preciso tratar o locale em conjunto. No Media também, title e description (escalares) e file (a instrução de ingestão) são mapas por locale. O JSON que não é Content nem Media, como /payload ou uma resposta HTTP, não é afetado por essa regra (mantém a estrutura definida pelo esquema, e um escalar continua sendo um escalar).

Leitura

• Para obter um escalar, especifique até o locale: { /<name>/fields/<field>/<locale> } (por exemplo, { /post/fields/title/en-US }).
• Sem locale, { /<name>/fields/<field> } retorna o objeto completo do mapa por locale.
• Um campo localized:false fica somente no bucket do locale padrão, portanto leia-o com o código desse locale padrão.

Escrita (os fields de ResourceCreate, ResourceUpdate e ResourcePatch)

O valor é um mapa por locale, { "<locale>": <expressão de valor escalar> }. É simétrico com a leitura.

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

• ResourceCreate deve incluir o bucket do locale padrão do Space em todos os campos que preenche (a regra default-locale).
• ResourceUpdate é uma substituição completa. Os campos e locales ausentes de fields são removidos (incluindo o arquivo).
• ResourcePatch atualiza somente os campos e buckets especificados (os demais campos e locales são mantidos).
• Exclusão com um null literal: quando o valor é um null literal, esse bucket (field, locale) é excluído (a forma padrão de esvaziar um locale específico em um Patch). "" (uma string vazia) não é uma exclusão, mas define um valor vazio. Quando uma expressão de valor ({ /ptr }) é avaliada como null em tempo de execução, não é uma exclusão, mas um erro (um payload ausente não é ignorado silenciosamente). Somente um null literal exclui.
• Media file: o valor não é um escalar, mas uma instrução de ingestão, { "source": …, "encoding": "url"|"base64" }. O que a ingestão de fato faz é abordado em ResourceCreate no Catálogo de statements.
• Coloque um campo localized:false somente no bucket do locale padrão.
• O código de locale (a chave do mapa) também pode ser uma referência { /ptr } (veja acima As chaves também podem ser referências). Use isso para criar um locale dinâmico.

Campo de conveniência locale

Ao passar locale para ResourceCreate, ResourceUpdate ou ResourcePatch, o motor envolve automaticamente cada valor de fields em um bucket { <locale>: valor }. Ou seja, basta passar escalares.

// os dois abaixo são 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" } } }

Se você passar locale enquanto o valor já aninha um mapa por locale ({ "en-US": … }), ocorre um aninhamento duplo como { <locale>: { "en-US": … } } (erro do autor). Padronize um único estilo: com locale, use somente escalares; sem ele, use somente mapas de locale explícitos.

O locale em where e order

• Em where e order, para fields.X o motor aplica automaticamente o locale padrão do Space (igual a uma consulta na CMA).
• Para especificar um determinado locale, indique-o explicitamente como fields.X.<locale>.

"where": { "fields.slug": { "eq": "{ /payload/fields/slug }" } }   // slug do locale padrão
"where": { "fields.title.ko-KR": { "prefix": "안" } }              // locale específico

Erros

São os códigos que aparecem quando uma regra das expressões de valor é violada. A verificação acontece no salvamento. Os códigos que violam as outras restrições estáticas da definição estão em Erros em Semântica de execução, restrições e segurança, e os que aparecem na chamada, em Erros em Recurso e endpoints do Script. Para os códigos comuns a todos os recursos, consulte Erros comuns.

Documentos relacionados

• Catálogo de statements: os campos e resultados dos 25 tipos de statement que usam expressões de valor.
• Semântica de execução, restrições e segurança: ordem de execução, erros, bloqueio otimista e restrições estáticas.
• Cookbook: exemplos completos que combinam expressões de valor.
• Visão geral do Script: a estrutura de nível superior e o tempo concedido a uma execução.