Communitygithub.com

jsonlogic

Compétences pour travailler avec les règles métier JsonLogic — le format de logique conditionnelle basé sur JSON de jsonlogic.com. Utilisé quand l'utilisateur souhaite transformer une exigence métier en règle JsonLogic, a besoin d'explications ou de débogage d'une expression JsonLogic existante, demande si une règle est valide, veut exécuter du JsonLogic dans un langage spécifique (JavaScript, TypeScript, Python, Ruby, Java, PHP, Go, C#, autres), choisit ou compare une bibliothèque JsonLogic, ou intègre JsonLogic dans une application. Déclenché sur les mentions de JsonLogic, json-logic, les objets de règles JSON de la forme {"var": ...}, ou les demandes d'exprimer des conditions et règles métier sous forme de JSON portable. Ne pas utiliser pour les tâches de programmation générales qui n'impliquent pas le format JsonLogic.

Qu'est-ce que jsonlogic ?

Cette compétence permet à un agent IA de travailler avec le format JsonLogic, un petit format portable pour exprimer une logique conditionnelle sous forme de JSON. Elle est utile pour les développeurs et les intégrateurs qui doivent créer, valider, déboguer ou exécuter des règles JsonLogic dans divers langages de programmation. La compétence prend en charge l'exécution de JsonLogic via des bibliothèques spécifiques (json-logic-js, json-logic-rb, maykin-json-logic-py, etc.), la validation des règles avec des cas de test, et la génération d'artefacts interactifs (playground HTML) pour visualiser et tester les règles en temps réel. Elle offre également des conseils structurés pour la rédaction de règles, le débogage, et la gestion des opérations non prises en charge. Les plateformes cibles incluent les agents de codage comme Claude Code, Cursor, Codex, et tout outil d'IA qui nécessite une manipulation précise des règles JsonLogic.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait jsonlogic ?

Une compétence pour travailler avec JsonLogic.

JsonLogic est un petit format portable pour exprimer une logique conditionnelle sous forme de JSON.

Le standard JsonLogic est le format de règle universel et définit sa sémantique. Une règle à ce niveau est indépendante du langage. Voir references/jsonlogic.md et references/operations.md.

Une bibliothèque spécifique est le code qui exécute JsonLogic dans un langage particulier, comme json-logic-js pour JavaScript ou json-logic-rb pour Ruby. Les bibliothèques peuvent différer dans les opérations qu'elles prennent en charge, ainsi que dans leur forme d'API et leur gestion des erreurs.

Exécution de JsonLogic

Bibliothèque

Si une implémentation spécifique est nommée, comme json-logic-js, utilisez cette implémentation exacte. Un nom de langage seul, comme "en Python", signifie utilisez la bibliothèque pour ce langage depuis references/libraries.md. Si ni une bibliothèque ni un langage n'est nommé, utilisez par défaut scripts/jsonlogic.rb.

Prise en charge

Une règle peut être une JsonLogic valide et ne pas être prise en charge par la bibliothèque sélectionnée ou sa version actuelle. Signalez les opérations non prises en charge. Ne réécrivez jamais une règle JsonLogic valide simplement parce qu'une bibliothèque ne peut pas l'exécuter. Dites à quel niveau se trouve la limitation et proposez les véritables options :

  • une opération personnalisée
  • une bibliothèque différente si l'opération n'est pas prise en charge dans l'implémentation spécifique
  • un changement de logique

Artefact de Playground

Chaque fois qu'une règle concrète est en jeu (créée, expliquée, corrigée ou exécutée), affichez-la en direct au lieu de la décrire uniquement dans le texte : initialisez assets/playground.html avec cette règle et ces données, puis publiez-la avec l'outil Artifact. Cela s'exécute sous le compte de la personne qui a installé la compétence — chaque appel de publication crée l'artefact sous son propre compte, donc cela fonctionne de la même manière pour chaque installateur sans étape de partage nécessaire. L'artefact est privé par défaut, et la publication ici met simplement à jour la même URL, donc il n'y a pas de décision distincte à vérifier à chaque fois.

Deux fichiers, un statique et un modelé : assets/jsonlogic-core.js est l'interpréteur JsonLogic — il ne change jamais entre les invocations, donc publiez-le une fois par conversation (via le paramètre files de l'outil Artifact) et jamais plus. assets/playground.html est la page fine avec les espaces réservés ci-dessous ; c'est le seul qui est re-modelé et republié à chaque modification.

  1. Lisez assets/playground.html. C'est une page de conception fixe (règle, résultat en direct, données) — ne modifiez jamais manuellement son CSS/disposition ; seuls les espaces réservés ci-dessous changent par invocation.
  2. Remplacez __INITIAL_RULE__ et __INITIAL_DATA__ par les objets règle/données, chacun sous forme de littéral JS/JSON (le résultat de JSON.stringify(...), valide pour être inséré tel quel). Pas encore de règle concrète → laissez les deux inchangés, le modèle revient à une valeur par défaut intégrée.
  3. Remplacez __CURRENT_LANG_MODE__ par "ruby" lorsque le langage cible est Ruby, sinon "jsonlogic" (tous les autres langages présentés ici suivent les règles de vérité/fausseté de JsonLogic ; seul Ruby diverge). Aucun langage décidé encore → laissez-le inchangé, revient à "jsonlogic".
  4. Remplacez __VERIFY_LIB_LABEL__ par la même bibliothèque Exécution de JsonLogic → Bibliothèque (ci-dessus) résolue pour cette tâche — c'est ce que le bouton "Vérifier dans le chat" de la page nomme lorsqu'il demande de confirmer contre l'implémentation réelle, donc il doit correspondre, pas par défaut à Ruby simplement parce que c'est le repli de ce fichier :
    • 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)"
    • Tout autre langage depuis references/libraries.md → le nom de cette bibliothèque tel qu'il y est donné. Aucun langage/bibliothèque décidé encore → laissez-le inchangé, revient à "json-logic-rb (scripts/jsonlogic.rb)" de Ruby, correspondant au défaut de cette compétence.
  5. Écrivez le résultat dans un fichier de travail et publiez-le — la première fois dans une conversation : outil Artifact, action:"publish", le chemin de ce fichier, title:"JSON Logic Playground", icon:"code", plus files:{"jsonlogic-core.js":"assets/jsonlogic-core.js"} pour que l'interpréteur soit livré à côté sans modification.
  6. Chaque fois que la règle, les données ou le langage changent plus tard dans la même conversation, refaites les étapes 1–4 avec les nouvelles valeurs et publiez à nouveau avec le même chemin de fichier et la même url — mais omettez files cette fois, puisque jsonlogic-core.js ne change jamais et qu'un fichier omis est conservé tel quel. Cela met à jour le même artefact sur place au lieu d'en créer un nouveau.

Sautez cela pour les demandes qui ne produisent jamais de règle concrète (par exemple, "que fait missing ?").

L'utilisateur peut modifier la règle/les données directement dans l'artefact pour tester des choses — c'est le but, il recalcule en direct. Ne republiez jamais par-dessus ces modifications manuelles. Republiez uniquement lorsque l'utilisateur demande une nouvelle règle ou condition modifiée dans le chat.

Rédaction de JsonLogic

Étape 1 : Obtenez la forme des données

Demandez toujours comment obtenir les noms de champs des données avant de créer une nouvelle règle. Présentez cela comme un choix. Utilisez le mécanisme de question structurée du client, tel que des boutons ou un sélecteur, lorsqu'il est disponible. Sinon, présentez les choix sous forme de texte brut.

Question : "Comment dois-je obtenir les noms de champs de vos données ?". Proposez trois options :

  • Option Schéma — "Je vais coller un schéma — JSON Schema, OpenAPI, n'importe quel format."
  • Option Données d'exemple — "Je vais coller un exemple JSON réel."
  • Option Deviner simplement — "Déduire les noms de champs de ma description."

Le dialogue ne fait que choisir la méthode. La réponse réelle vient toujours sous forme de message de suivi normal, pas à l'intérieur du dialogue lui-même.

Étape 2 : Construisez l'expression

Écrivez la règle en utilisant les noms de champs de l'Étape 1.

Avant d'écrire une nouvelle règle, consultez references/operations.md pour la liste complète prise en charge et examples/ pour des modèles éprouvés. Pour les cas de test réels en amont par opérateur, voir references/tests/.

Personnalisation

N'attendez pas que JsonLogic inclue toutes les opérations spécialisées. Il est intentionnellement petit et pas un langage de programmation. Il ne fera jamais tout. Cependant JsonLogic prend en charge les extensions. Avant de recourir à une solution personnalisée, voyez si vous pouvez exprimer votre logique en utilisant les opérations prises en charge (intégrées). Souvent, un simple changement de perspective suffit pour faire le travail avec ce qui est déjà là.

Étape 3 : Expliquez ce qu'il fait

Couvrez :

  • l'exigence encodée
  • les opérations utilisées et ce que chacune fait
  • la forme d'entrée attendue
  • ce que renvoie la règle
  • les cas limites à signaler (champs manquants, coercition de type, tableaux vides)

Sautez les éléments qui ne s'appliquent pas.

Informations manquantes

Si la condition métier n'est pas claire — vous devez demander ce que la règle doit vérifier, mais ne demandez pas des choses que vous pouvez déjà résoudre à partir du contexte.

Valider JsonLogic

Vérifier la forme par rapport à references/jsonlogic.md, references/operations.md, ou scripts/validate_skill.rb confirme seulement que la règle a la forme de JsonLogic.

La validation réelle signifie écrire des cas de test et les exécuter via scripts/jsonlogic.rb. Voir references/testing.md pour savoir comment les choisir. Couvrez le cas normal et la limite, mais privilégiez les cas limites surtout : champs manquants, tableaux vides, types inattendus. Une règle sans cas de test n'est pas sûre à transmettre — il n'y a aucun moyen de garantir qu'elle se comporte comme prévu.

Pour les opérateurs individuels qu'une règle utilise, vérifiez references/tests/ d'abord — des cas en amont réels pour à la fois le noyau (core.json) et les extensions communautaires (community/), regroupés localement. Réutilisez un cas correspondant comme vérification de cohérence avant d'en écrire de nouveaux à partir de zéro ; ceux-ci testent les opérateurs isolément, pas la logique métier réelle de la règle, donc ajoutez toujours des cas spécifiques à la règle en plus.

Déboguer JsonLogic

Étape 1 : Reproduisez-le

Utilisez Exécution de JsonLogic avec la règle et les données telles que rapportées. Voyez la sortie réelle vous-même avant de diagnostiquer quoi que ce soit.

Étape 2 : Trouvez la cause réelle

Conduisez avec la cause réelle, pas seulement le symptôme — coupables courants : coercition de type, champs manquants, mauvaise utilisation de l'opérateur.

Étape 3 : Corrigez et vérifiez

Donnez la règle corrigée, puis refaites l'Étape 1 avec la correction pour confirmer que la nouvelle sortie est correcte. Si la correction doit être remise sous forme de code exécutable, continuez à Exécuter JsonLogic ci-dessous.

Après toute action

Vérifier l'exécution

Voir Exécution de JsonLogic ci-dessus pour exécuter effectivement la règle. S'il n'y a pas encore d'exemple de données sous la main, créez-en un représentatif d'abord. La vérification a besoin d'une entrée réelle pour s'exécuter, pas seulement d'une description de ce que la règle doit faire.

Signaler les préoccupations

N'affirmez pas que JsonLogic est "sûr" simplement parce que c'est du JSON.

Fichiers de référence

Lisez-les au besoin plutôt que de tout charger en amont :

  • references/jsonlogic.md — sémantique de base : vérité, coercition de type, résolution de chemin var, comment se comportent les données manquantes, ce que signifie "conforme".
  • references/operations.md — chaque opération standard : syntaxe plus notes de comportement utiles (court-circuit, comparaisons à trois arguments, current/accumulator de reduce, etc.).
  • references/libraries.md — le paysage des bibliothèques à travers les langages : ce qui a été trouvé, ce qui a été vérifié, ce qui ne l'a pas été. Lisez avant d'écrire tout code spécifique à un langage, y compris pour les langages non listés — vérifiez d'abord là plutôt que de supposer qu'aucune n'existe.
  • references/testing.md — comment vérifier une règle ou une implémentation, et comment être honnête sur ce que signifie "vérifié" dans une réponse donnée.
  • references/tests/ — cas de test en amont regroupés (noyau + extensions communautaires) pour valider les opérateurs individuels.
  • examples/ — exemples éprouvés :

Skills associés