La structure des données

Les paramètres de la législation socio-fiscale française forment des séries de données évoluant dans le temps. On présente ici la structuration choisie pour représenter ces données et les règles de contribution associées.

Le format YAML

Le format YAML est le format retenu pour les paramètres législatifs des barèmes IPP et du moteur OpenFisca. Il permet de représenter de façon lisible des informations élaborées comme une combinaison de listes et de dictionnaires imbriqués.

Il est nécessaire de bien respecter :

l'indentation introduisant les sous-structures
les tirets - marquant des listes
les deux points séparant les clés des valeurs dans un dictionnaire

Enfin, c'est un schéma bien précis qui est attendu, avec des champs obligatoires et d'autres facultatifs. Tous ces champs doivent également suivre une structure plus ou moins stricte.

Toute modification est scrutée par un validateur qui détecte les éventuelles erreurs sur les branches suivies.

Les champs obligatoires

Les paramètres choisis doivent représenter la loi le plus fidèlement possible. Chaque évolution d'une valeur doit être justifiée par une référence législative.

Ainsi, afin de respecter ce principe tout en réduisant au strict minimum la charge pour le contributeur, seuls trois champs sont obligatoires lors de la création d'un paramètre :

la description longue du paramètre ⎪ champ label correspondant à l'ancien champ description
les valeurs du paramètre ⎪ champ values (pour les valeurs uniques) ou champ brackets (pour les barèmes)
la référence législative ⎪ champ reference qui se situe dans le champ metadata

Comme ces champs sont obligatoires, leur présence et leur format seront soumis au validateur automatique. Par convention, les commentaires (# commentaires) sont interdits et seront supprimés automatiquement à la validation. Il est ainsi recommandé de mettre ses annotations directement dans le champ facultatif documentation.

Pour savoir comment compléter les champs obligatoires, veuillez consulter les documentations suivantes :

Les champs facultatifs : `metadata`

Les champs dits facultatifs sont rassemblés dans les métadonnées. Ils sont dès lors facultatifs au sens d'OpenFisca avec lequel le format est partagé et qui n'impose pas de contrainte dans le champ metadata. Il reste néanmoins fortement conseillé de les renseigner pour la législation socio-fiscale française.

OpenFisca traite de différents pays. Les paramètres qui nous intéressent ici concernent la législation française où les champs retenus sont les suivants :

Exemple d'un paramètre complet

description: Montant (en % de la BMAF) de l'allocation d'adoption (AA), une des prestations sociales familiales pour la petite enfance
values:
  1995-01-01:
    value: 0.3
  1996-08-01:
    value: 0.4595
  2007-01-01:
    value: null
metadata:
  short_label: Montant
  last_value_still_valid_on: "2022-02-22"
  description_en: "Adoption allowance (AA): General conditions and amounts"
  ipp_csv_id: aa_montant
  unit: BMAF
  reference:
    1996-08-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
    2007-01-01:
    - title: Décret n°2020-1453 du 27 novembre 2020
      href: https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000042574431
  official_journal_date:
    1995-01-01: "1995-02-17"
    1996-08-01: "1996-07-06"
    2007-01-01: "2003-12-19"
  notes:
    1995-01-01:
    - title: Pas cumulable avec l'ASF. Pour les enfants nés à partir du 01/01/1995. Le décret 95-165 du 16/02/1995 crée l'Allocation à l'Adoption
    1996-08-01:
    - title: Loi qui assure la parité des droits sociaux attachés à la naissance et à l'adoption. Loi qui aligne l'allocation d'adoption sur l'APJE. Mêmes montants et mêmes plafonds (par contre, durée de l'aide, à fixer par décret).
documentation: |
  Après 2007, la PAJE remplace en partie l'allocation d'adoption. Mais, transition progressive, jusqu'à fin 2006 (cf. art. 60, VIII de la loi).

FAQ - Cas particuliers et questions ouvertes

Selon les paramètres, il arrive de rencontrer des cas un peu particuliers. Voici une liste des décisions prises pour chacun de ces cas. À noter qu'elles n'ont pas fait l'objet d'une RFC (Request For Comment de la communauté de contributeurs), et ne sont donc pas le résultat d'un consensus, mais plutôt de bonnes pratiques observées.

Ajout de références 'récentes'

Est-ce que je peux ajouter une reference qui a une date postérieure à la dernière valeur du paramètre ?

Exemples :

La référence (article) d'une valeur a changé, mais pas sa valeur.
La seule référence en ma possession est postérieure à la dernière valeur.
Le dispositif a changé (réforme) mais pas cette valeur.
Je trouve une référence récente intéressante qui détaille un mécanisme ou une réforme, mais pas spécifiquement le paramètre.

Dans les cas 1, 2 et 3, on peut ajouter cette référence si celle-ci n'est pas redondante avec les références précédentes (par redondant, on entend par exemple : le même lien LégiFrance mais pas à la même date).

Dans le cas 4, cette référence étant un peu plus large que la value, il faudra plutôt l'ajouter dans le champ documentation.

Le `short_label` des paramètres "feuille" peut porter à confusion

Le short_label des paramètres au bas de l'arborescence doit être court tout en étant signifiant.

Pour le paramètre parameters/prestations_sociales/prestations_familiales/education_presence_parentale/ars/ars_m/taux_primaire.yaml

Le paramètre noeud ars_m a pour short_label : "Montants de l'allocation de rentrée scolaire".

En théorie, on pourrait conclure, que le short_label du paramètre "feuille" taux_primaire devrait être simplement :

Première tranche d'âge

En pratique, on va privilégier la redondance et préférer :

Montant pour la première tranche d'âge

Cela permet d'éviter le quiproquo suivant : que le paramètre soit compris comme étant le seuil de la première tranche d'âge.