Communitygithub.com

jsonlogic

Trabalhe com regras de negócio JsonLogic — o formato de lógica condicional baseado em JSON em jsonlogic.com. Use sempre que o usuário quiser transformar um requisito de negócio em uma regra JsonLogic, precisar que uma expressão JsonLogic existente seja explicada ou depurada, perguntar se uma regra é válida, quiser executar JsonLogic em uma linguagem específica (JavaScript, TypeScript, Python, Ruby, Java, PHP, Go, C#, outras), estiver escolhendo ou comparando uma biblioteca JsonLogic, ou estiver integrando JsonLogic em uma aplicação. Acione em menções a JsonLogic, json-logic, objetos de regra JSON no formato {"var": ...}, ou solicitações para expressar condições e regras de negócio como JSON portátil. Não use para tarefas de programação em geral que não envolvam o formato JsonLogic.

O que é jsonlogic?

Esta skill capacita o assistente a trabalhar com o formato JsonLogic, um padrão portátil e universal para expressar lógica condicional como JSON. Ela permite criar, explicar, depurar, validar e executar regras JsonLogic em várias linguagens de programação (JavaScript, Python, Ruby, etc.), utilizando a biblioteca apropriada para cada uma. A skill se destaca por oferecer um passo a passo claro: primeiro, obtém a estrutura dos dados via esquema, amostra ou inferência; depois, constrói a expressão usando as operações padrão; em seguida, explica o comportamento da regra, cobrindo requisitos, operações e casos extremos; por fim, sugere a verificação real com casos de teste. Além disso, ela integra um 'Playground' interativo que permite visualizar e testar as regras em tempo real, atualizando o artefato sempre que a regra, os dados ou a linguagem alvo mudam. A skill também fornece acesso a referências locais sobre semântica, operações, bibliotecas e testes, garantindo que o usuário tenha tudo o que precisa para implementar regras de negócio robustas e portáteis.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/valeryia-piatrova/jsonlogic-skill/tree/main

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que jsonlogic faz?

Uma skill para trabalhar com JsonLogic.

JsonLogic é um formato pequeno e portátil para expressar lógica condicional como JSON.

O padrão JsonLogic é o formato universal de regras e define sua semântica. Uma regra neste nível é independente de linguagem. Consulte references/jsonlogic.md e references/operations.md.

Uma biblioteca específica é o código que executa JsonLogic em uma determinada linguagem, como json-logic-js para JavaScript ou json-logic-rb para Ruby. As bibliotecas podem diferir nas operações que suportam, bem como na forma da API e no tratamento de erros.

Executando JsonLogic

Biblioteca

Se uma implementação específica for nomeada, como json-logic-js, use essa implementação exata. Apenas um nome de linguagem, como "em Python", significa usar a biblioteca para essa linguagem em references/libraries.md. Se nem uma biblioteca nem uma linguagem forem nomeadas, o padrão é scripts/jsonlogic.rb.

Suporte

Uma regra pode ser JsonLogic válida e ainda assim não ser suportada pela biblioteca selecionada ou sua versão atual. Sinalize operações não suportadas. Nunca reescreva uma regra JsonLogic válida apenas porque uma biblioteca não consegue executá-la. Diga em qual nível está a limitação e ofereça as opções reais:

  • uma operação personalizada
  • uma biblioteca diferente, se a operação não for suportada na implementação específica
  • alteração de lógica

Artefato do Playground

Sempre que uma regra concreta estiver em jogo (criada, explicada, corrigida ou executada), renderize-a ao vivo em vez de apenas descrevê-la em texto: preencha assets/playground.html com essa regra e dados e, em seguida, publique-o com a ferramenta Artifact. Isso é executado sob quem instalou a skill — cada chamada de publicação cria o artefato na própria conta dessa pessoa, então funciona da mesma forma para todos os instaladores, sem necessidade de etapa de compartilhamento. O artefato é privado por padrão, e publicar aqui apenas atualiza a mesma URL, portanto não há uma decisão separada a ser verificada a cada vez.

Dois arquivos, um estático e um modelado: assets/jsonlogic-core.js é o interpretador JsonLogic — ele nunca muda entre invocações, então publique-o uma vez por conversa (via o parâmetro files da ferramenta Artifact) e nunca mais. assets/playground.html é a página enxuta com os placeholders abaixo; é o único que é remodelado e republicado a cada alteração.

  1. Leia assets/playground.html. É uma página de design fixo (regra, resultado ao vivo, dados) — nunca edite manualmente seu CSS/layout; apenas os placeholders abaixo mudam por invocação.
  2. Substitua __INITIAL_RULE__ e __INITIAL_DATA__ pelos objetos de regra/dados, cada um como um literal JS/JSON (a saída de JSON.stringify(...), válido para inserir como está). Ainda não há regra concreta → deixe ambos intactos, o modelo volta para um padrão embutido.
  3. Substitua __CURRENT_LANG_MODE__ por "ruby" quando a linguagem alvo for Ruby, caso contrário, "jsonlogic" (todas as outras linguagens mostradas aqui seguem as regras de truthy/falsy do próprio JsonLogic; apenas o Ruby diverge). Nenhuma linguagem decidida ainda → deixe intacto, volta para "jsonlogic".
  4. Substitua __VERIFY_LIB_LABEL__ pela mesma biblioteca Executando JsonLogic → Biblioteca (acima) resolvida para esta tarefa — este é o nome que o botão "Verificar no chat" da página usa ao pedir para confirmar contra a implementação real, portanto deve corresponder, não padronizar para Ruby só porque é o fallback deste próprio arquivo:
    • Ruby → "json-logic-rb (scripts/jsonlogic.rb)"
    • JavaScript / TypeScript → "json-logic-js"
    • Python → "maykin-json-logic-py"
    • Java → "json-logic-java"
    • PHP → "json-logic-php (jwadhams/json-logic-php)"
    • Go → "diegoholiveira/jsonlogic"
    • C# / .NET → "JsonLogic (json-everything)"
    • Qualquer outra linguagem de references/libraries.md → o nome dessa biblioteca conforme fornecido lá. Nenhuma linguagem/biblioteca decidida ainda → deixe intacto, volta para o Ruby "json-logic-rb (scripts/jsonlogic.rb)", correspondendo ao padrão desta própria skill.
  5. Escreva o resultado em um arquivo de trabalho e publique-o — na primeira vez em uma conversa: ferramenta Artifact, action:"publish", o caminho desse arquivo, title:"JSON Logic Playground", icon:"code", além de files:{"jsonlogic-core.js":"assets/jsonlogic-core.js"} para que o interpretador seja enviado junto inalterado.
  6. Sempre que a regra, os dados ou a linguagem mudarem posteriormente na mesma conversa, refaça os passos 1–4 com os novos valores e publique novamente com o mesmo caminho de arquivo e a mesma url — mas omita files desta vez, já que jsonlogic-core.js nunca muda e um arquivo omitido é mantido como está. Isso atualiza o mesmo artefato no lugar, em vez de criar um novo.

Pule isso para solicitações que nunca produzem uma regra concreta (por exemplo, "o que missing faz?").

O usuário pode editar a regra/dados diretamente no artefato para testar coisas — esse é o objetivo, ele recalcula ao vivo. Nunca republique sobre essas edições manuais. Publique novamente apenas quando o usuário solicitar uma regra/condição nova ou alterada no chat.

Escrevendo JsonLogic

Passo 1: Obter a estrutura dos dados

Sempre pergunte como obter os nomes dos campos dos dados antes de criar uma nova regra. Apresente isso como uma escolha. Use o mecanismo de pergunta estruturada do cliente, como botões ou um seletor, quando disponível. Caso contrário, apresente as escolhas como texto simples.

Pergunta: "Como devo obter os nomes dos campos dos seus dados?". Ofereça três opções:

  • Opção Esquema — "Vou colar um esquema — JSON Schema, OpenAPI, qualquer formato."
  • Opção Dados de exemplo — "Vou colar um exemplo JSON real."
  • Opção Apenas adivinhar — "Inferir nomes de campos a partir da minha descrição."

O diálogo apenas seleciona o método. A resposta real ainda vem como uma mensagem de acompanhamento normal, não dentro do próprio diálogo.

Passo 2: Construir a expressão

Escreva a regra usando os nomes de campos do Passo 1.

Antes de escrever uma nova regra, verifique references/operations.md para a lista completa suportada e examples/ para padrões trabalhados. Para casos de teste reais upstream por operador, consulte references/tests/.

Personalização

Não espere que o JsonLogic inclua todas as operações especializadas. Ele é intencionalmente pequeno e não é uma linguagem de programação. Nunca fará tudo. No entanto, o JsonLogic suporta extensões. Antes de recorrer a uma solução personalizada, veja se você pode expressar sua lógica usando as operações suportadas (embutidas). Muitas vezes, uma simples mudança de perspectiva é tudo que você precisa para fazer o trabalho com o que já existe.

Passo 3: Explicar o que faz

Cubra:

  • o requisito sendo codificado
  • as operações usadas e o que cada uma faz
  • a forma esperada de entrada
  • o que a regra retorna
  • casos extremos que valem a pena sinalizar (campos ausentes, coerção de tipo, arrays vazios)

Pule itens que não se aplicam.

Informação faltando

Se a condição de negócio não estiver clara – você deve perguntar o que a regra deve verificar, mas não pergunte sobre coisas que você já pode resolver a partir do contexto.

Validar JsonLogic

Verificar a forma contra references/jsonlogic.md, references/operations.md ou scripts/validate_skill.rb apenas confirma que a regra tem a forma de JsonLogic.

Validação real significa escrever casos de teste e executá-los através de scripts/jsonlogic.rb. Consulte references/testing.md para saber como escolhê-los. Cubra o caso normal e o limite, mas pese mais para casos extremos, especialmente: campos ausentes, arrays vazios, tipos inesperados. Uma regra sem casos de teste não é segura para ser entregue — não há como garantir que ela se comporta conforme o esperado.

Para os operadores individuais que uma regra usa, verifique references/tests/ primeiro — casos upstream reais tanto para a especificação principal (core.json) quanto para as extensões da comunidade (community/), agrupados localmente. Reutilize um caso correspondente como uma verificação de sanidade antes de escrever novos do zero; estes testam os operadores isoladamente, não a lógica de negócio real da regra, portanto ainda adicione casos específicos da regra por cima.

Depurar JsonLogic

Passo 1: Reproduzir

Use Executando JsonLogic com a regra e os dados conforme relatados. Veja a saída real você mesmo antes de diagnosticar qualquer coisa.

Passo 2: Encontrar a causa real

Comece com a causa real, não apenas o sintoma — culpados comuns: coerção de tipo, campos ausentes, uso incorreto de operador.

Passo 3: Corrigir e verificar

Forneça a regra corrigida e, em seguida, repita o Passo 1 com a correção para confirmar que a nova saída está correta. Se a correção precisar ser entregue como código executável, prossiga para Executar JsonLogic abaixo.

Após qualquer

Verificar execução

Consulte Executando JsonLogic acima para realmente executar a regra. Se ainda não houver um exemplo de dados disponível, crie um representativo primeiro. A verificação precisa de entrada real para ser executada, não apenas uma descrição do que a regra deve fazer.

Sinalizar preocupações

Não afirme que JsonLogic é "seguro" apenas porque é JSON.

Arquivos de referência

Leia estes conforme necessário, em vez de carregar tudo de uma vez:

  • references/jsonlogic.md — semântica principal: verdade, coerção de tipo, resolução de caminho var, como dados ausentes se comportam, o que significa "conforme".
  • references/operations.md — todas as operações padrão: sintaxe mais notas de comportamento que valem a pena conhecer (curto-circuito, comparações de três argumentos, current/accumulator do reduce, etc).
  • references/libraries.md — o panorama de bibliotecas entre linguagens: o que foi encontrado, o que foi verificado, o que não foi. Leia antes de escrever qualquer código específico de linguagem, inclusive para linguagens não listadas — verifique primeiro lá, em vez de assumir que nenhuma existe.
  • references/testing.md — como verificar uma regra ou implementação e como ser honesto sobre o que "verificado" significa em uma determinada resposta.
  • references/tests/ — casos de teste upstream agrupados (especificação principal + extensões da comunidade) para validar operadores individuais.
  • examples/ — exemplos trabalhados:

Habilidades Relacionadas