- L’IRS américain a publié en open source son nouveau Tax Withholding Estimator (TWE), dont le principe de conception central est une structure qui modélise le droit fiscal américain sous forme de spécification déclarative basée sur XML
- La logique de calcul fiscal de TWE est construite sur un moteur logique appelé Fact Graph, qui représente chaque élément fiscal comme un graphe de dépendances de « faits » définis en XML
- Implémenter la logique fiscale dans un langage impératif comme JavaScript entraîne des problèmes de gestion de l’ordre d’exécution, de perte des valeurs intermédiaires et d’exposition des détails d’implémentation, ce qui rend une approche déclarative indispensable
- JSON n’est pas adapté au traitement d’expressions imbriquées arbitraires, alors qu’avec XML, les balises elles-mêmes indiquent le type d’objet, ce qui le rend bien plus avantageux pour construire un DSL
- XML permet aussi de tirer gratuitement parti d’un écosystème d’outils mature comme XPath, ce qui en fait l’option la plus rentable pour des spécifications déclaratives multiplateformes
Fact Graph : le droit fiscal américain exprimé en XML
- Le Tax Withholding Estimator (TWE) publié par l’IRS est un outil permettant aux contribuables de saisir leurs revenus et déductions afin d’estimer leur impôt et leur retenue à la source
- Le projet est publié en open source et accepte aussi les contributions du public
- TWE est un site statique généré à partir de deux configurations XML, dont la première est un Fact Dictionary qui représente le droit fiscal américain
- Fact Graph est un moteur logique initialement conçu pour le projet IRS Direct File, qui calcule l’obligation fiscale et la retenue à la source d’un contribuable à partir des faits définis dans le Fact Dictionary
- Chaque fait est défini en XML ; par exemple,
/totalOwed est représenté comme un fait dérivé (Derived) qui soustrait /totalPayments de /totalTax
- Le « montant total dû » (
total owed) est la différence entre l’impôt total sur le revenu (total tax) et les montants déjà payés (total payments)
- Les crédits remboursables (
refundable credits) sont des crédits d’impôt pouvant rendre le solde fiscal négatif ; des éléments comme l’Earned Income Credit, le Child Tax Credit et l’American Opportunity Credit sont additionnés avec <Add>
- Les crédits non remboursables (
non-refundable credits) ne peuvent réduire la charge fiscale que jusqu’à 0 ; l’opérateur <GreaterOf> sert à choisir la plus grande valeur entre 0 et (impôt provisoire - crédits non remboursables)
- Les valeurs saisies par l’utilisateur utilisent la balise
<Writable> au lieu de <Derived>, avec des types comme <Dollar/> et <Boolean/> pour indiquer le type de valeur
- Les faits dépendent les uns des autres et forment une structure en graphe qui produit les chiffres fiscaux finaux
Pourquoi la logique fiscale a besoin de spécifications déclaratives
- En JavaScript, on pourrait écrire le même calcul de manière concise, comme
const totalOwed = totalTax - totalPayments, mais cela relève d’une approche impérative où l’exécution est séquentielle et où les étapes intermédiaires disparaissent ensuite
- Quand les dépendances deviennent profondes, des problèmes d’ordre d’exécution apparaissent : une fonction de saisie utilisateur comme
getInput() bloque tous les calculs suivants, et les questions elles-mêmes doivent changer selon, par exemple, la présence d’un conjoint
- Dans la logique d’agrégation des revenus de Social Security, des détails d’implémentation JavaScript comme
map et reduce deviennent visibles, alors que <CollectionSum> en XML exprime le concept mathématique fiscal lui-même
<Dependency path="/socialSecuritySources/*/totalFederalTaxesPaid"/> permet de sommer les éléments d’une collection
- Le Fact Dictionary adopte une approche déclarative, où l’on décrit uniquement les calculs nommés et leurs dépendances, sans spécifier les étapes concrètes ni leur ordre d’exécution ; le moteur décide automatiquement de la manière d’exécuter
- L’avantage le plus important d’un modèle fiscal déclaratif est l’auditabilité et l’introspection : on peut demander au programme « comment ce nombre a-t-il été obtenu ? »
- Dans un programme impératif, les valeurs intermédiaires sont déjà jetées et ne peuvent être examinées qu’au moyen de logs ou d’un débogueur, ce qui ne passe pas à l’échelle lorsqu’il existe des centaines de calculs intermédiaires comme dans le droit fiscal américain
- Selon Chris Given, auteur initial de Fact Graph, Fact Graph est « un moyen de prouver que les éléments non demandés n’ont pas modifié le résultat fiscal, et que toutes les aides fiscales auxquelles on a droit sont bien prises en compte »
- Intuit, créateur de TurboTax, est arrivé à la même conclusion et a publié en 2020 un livre blanc sur un « Tax Knowledge Graph », mais son implémentation n’est pas publique
- Le Fact Graph de l’IRS est open source et dans le domaine public, ce qui permet à chacun de l’étudier, le partager et l’étendre
Pourquoi XML est bien mieux adapté aux DSL que JSON
- Si l’on tente d’utiliser JSON comme format de représentation déclarative du droit fiscal, le traitement d’expressions imbriquées arbitraires devient très peu pratique
- Comme la seule structure de données composite de JSON est l’objet, chaque objet enfant doit indiquer sa propre nature avec
"type", "kind", etc.
- En XML, le nom de la balise indique directement le type d’objet, sans déclaration supplémentaire
- La représentation JSON du même fait
/tentativeTaxNetNonRefundableCredits est en fait plus longue et plus complexe que sa version XML
- XML prend en charge les commentaires et gère raisonnablement les espaces et retours à la ligne, évitant ainsi plusieurs désagréments courants de JSON
- Les attributs et les éléments enfants nommés offrent, dans la conception du langage, une expressivité qui permet de choisir ce qu’il faut mettre en avant
- Il est possible de définir des types de données propres au domaine, comme la distinction entre « dollar » et « entier »
- Pour les textes descriptifs longs, XML est bien plus agréable à lire et à éditer manuellement que JSON
La polyvalence de XML et son écosystème d’outils
- Des syntaxes alternatives comme les S-expressions, Prolog ou KDL peuvent être plus agréables à lire que XML, mais utiliser XML permet d’obtenir gratuitement un parseur et tout un écosystème d’outils génériques
- Les S-expressions fonctionnent bien en Lisp, les termes Prolog en Prolog, mais XML peut être converti vers pratiquement n’importe quel format
- En Prolog, convertir du XML en termes Prolog est possible avec un seul prédicat
- La question d’un utilisateur de Hacker News, ok123456, demandant « pourquoi ne pas utiliser Prolog/Datalog ? » est aussi mentionnée ; c’est possible, mais XML l’emporte en polyvalence
- À propos de YAML, Chris Given indique qu’il ne faut « absolument jamais essayer d’exprimer la logique du droit fiscal américain en YAML »
- Exemple concret avec XPath : un script en une ligne de shell permet de faire une recherche floue dans les chemins des faits et d’afficher immédiatement la définition du chemin sélectionné
cat facts.xml | xpath -q -e '//Fact/@path' | grep -o '/[^"]*' | fzf pour rechercher un fait- Une fonction a aussi été ajoutée pour remonter la chaîne de dépendances et voir quels faits dépendent d’un fait donné
- Environ 60 lignes de script bash ont suffi pour créer un outil de débogage utilisé presque tous les jours
- Les membres de l’équipe ont eux aussi créé des outils de débogage rapides comparables, chacun dans son propre langage, en parsant trivialement le XML sans toucher à l’implémentation Scala de Fact Graph
- Le principal enseignement est que les formats génériques de représentation de données ont énormément de valeur, et que cette catégorie ne comprend en pratique que JSON et XML
- Dans la plupart des cas, il faut choisir JSON ; mais lorsqu’un DSL est nécessaire, XML est l’option la moins coûteuse, et cette efficacité économique permet à l’équipe de réserver son budget d’innovation à d’autres sujets
Points complémentaires
- Même des non-programmeurs peuvent lire du XML si le schéma est bien conçu, même s’il reste souhaitable de construire séparément des vues alternatives
- L’intérêt pour XML semble repartir récemment :
grex, l’outil de Jake Low qui convertit des documents XML en représentation plate orientée lignes, ou encore Xee de Martijn Faassen, un moteur XPath/XSLT moderne implémenté en Rust
- Les faits de TWE sont destinés à l’estimation de la retenue à la source et ne doivent pas être utilisés directement pour une déclaration fiscale
Aucun commentaire pour le moment.