Clôture de la RFC des paramètres

[DorineLam]

Issue de clôture de la RFC des métadonnées des paramètres : https://github.com/openfisca/openfisca-france/issues/1672

Issue réalisée dans le cadre la Journée de contribution OpenFisca France du 19 janvier 2023 qui décrit les décisions prises.

[DorineLam]

État des lieux des décisions prises

description devient label

Renommage en label.

Les contraintes :

• Obligatoire
• Le label est unique
• Il est auto-suffisant, c'est à dire que le contexte du paramètre ou le dispositif dans lequel il intervient est indiqué.
• Lors d'acronyme, toujours mettre le nom avant l'acronyme entre parenthèse.
• Si la périodicité n'est pas triviale, alors la préciser (ex : Montant mensuel)

Exemples de label : Taux de la contribution sociale généralisée (CSG) Montant de l'allocation d'adoption (AA)

et d'une contrainte d'unicité dans le système socio-fiscal.

description_en devient label_en

Est admis que le champ est maintenu. Est renommé label_en en cohérence avec les autres renommages

ux_name devient short_label

Renommage en short_label

Les contraintes :

• Facultatif
• n'est pas forcément unique
• le plus court possible
• retirer les unités
• Si la périodicité n'est pas triviale, alors la préciser (ex : Montant mensuel)

Exemples : Taux Montant

reference se structure avec un title et un href

Une référence est exigée à chaque ajout ou modification d'une valeur, afin d'identifier la loi d'où provient le paramètre. Cette référence peut être le lien vers le décret qui modifie la valeur, ou un lien direct vers l'article en vigueur ou, idéalement, les deux. Il est impératif que la référence soit officielle et il est préférable de sélectionner un article de loi codifié.

On demande systématiquement un intitulé title et une URL href pour chaque référence.

La référence est obligatoire.

• Nom : reference
• Échelle de déclaration : Champ metadata
• Cas d'usage :
  • Vérifier la validité d'une formule en consultant son origine légale.
  • Afficher l'intitulé de la source légale dans l'explorateur de législation.
  • Automatiser la détection d'un changement législatif.
• Exemples :

  base:
    values:
      2020-06-01:
        value: 124
      2020-10-01:
        value: 150
  metadata:
+   reference:
+     2020-06-01:
+     - title: Article 197, I.1. du Code général des impôts
+       href: https://www.legifrance.gouv.fr/codes/article_lc/LEGIARTI000042907517
+     - title: Décret n°2020-769 du 24/06/2020, art. 2
+       href: https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000042032514
+     2020-10-01:     
+       - title: Décret n°2020-1453 du 27 novembre 2020
+         href: https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000042574431

unit

Soutien pour le maintien, avec déplacement dans le nœud metadata et en normalisant les valeurs possibles au travers d'un fichier units.yaml.

Reste un chantier à traiter qui concerne les unités des barèmes (threshold_unit et rate_unit) cf le problème explicité ici par @sandcha : https://github.com/openfisca/openfisca-france/issues/1672#issuecomment-983810038

documentation

Le champ documentation est un texte libre, qui n'est pas lié à une date, qui peut être mis sur un nœud ou une feuille de l'arbre des paramètres. Il peut correspondre à une description du paramètre ou une définition ou une information métier. Pour éviter de dupliquer une documentation dans plusieurs paramètres, il est préférable de la mettre dans le parent commun.

Ce champ sert aussi à ne pas perdre ce qui était mis en commentaire dans les fichiers YAML, car maintenant les commentaires sont supprimés dans les phases de validation/conversion.

notes

Le champ notes est un texte libre qui est lié à une date et qui donc ne peut être mis que sur une feuille de l'arbre des paramètres. C'est une documentation en rapport avec une date de valeur.

Si une note concerne plusieurs paramètres elle doit être dupliquée pour chacun de ces paramètres.

Ce champ sert aussi à ne pas perdre ce qui était mis en commentaire dans les fichiers YAML, car maintenant les commentaires sont supprimés dans les phases de validation/conversion.

last_review devient last_value_still_valid_on

Cette metadata concerne la dernière valeur d’un paramètre. Il s’agit donc de ne vérifier qu’une seule valeur de la série : la dernière en vigueur. Ainsi, sa date est forcément postérieure à la dernière valeur du paramètre (et ceci peut facilement être vérifié en CI). last_value_still_valid_onest optionnel et permet ainsi la capitalisation progressive de cette information dans la base de paramètres.

Pour permettre la revue d’un tel champ, la MR doit indiquer la référence législative correspondante à date. Si l’url est une information nouvelle, le contributeur peut décider de l’ajouter dans les références.

Ce champ a suscité des réserves à garder en tête à l'usage :

• Coût de fonctionnement de la revue
• La valeur du champ repose sur la confiance accordée aux acteurs, et notamment sur le fait que la personne qui fait la revue prenne bien le temps de vérifier la référence indiquée en MR avant de valider un last_value_still_valid_on.