Normalisation des métadonnées des paramètres

[MattiSG]

RFC : normalisation des métadonnées des paramètres

Objet

Cette RFC vise à établir une liste des métadonnées à utiliser dans OpenFisca France pour les paramètres.

Contexte, Nécessité, Processus…

Cette issue est le résultat d'un éclatement de #1618 opéré afin de faciliter la lecture. Tout le contexte, ainsi que le catalogue des métadonnées à traiter, est donc donné dans https://github.com/openfisca/openfisca-france/issues/1618#issue-958097828. Il s'agit ici de continuer la conversation, uniquement sur les paramètres, en s'appuyant sur les résultats déjà obtenus pour les variables.

[MattiSG]

Version 0 d'une proposition pour description (métadonnée de Paramètre)

Fonctionnement actuel, sans changement.

---

• Nom : description
• Type : texte libre.
• Objet : donner un nom lisible au paramètre.
• Échelle de déclaration : Paramètre.
• Convention : contenir le nom de l'ensemble des nœuds traversés avec une expansion des abréviations et les abréviations entre parenthèses.
• Cas d'usage :
  • Désambiguer un paramètre dont le nom est une abréviation.
  • Rechercher et afficher un paramètre dans l'explorateur de législation.
• Exemples :
  • "Indicatrice d'imposition"
  • "Contribution exceptionnelle sur les hauts revenus"
• Lieu de documentation : openfisca.org/doc pour le format de données, CONTRIBUTING.md pour les conventions.

[MattiSG]

Version 1A d'une proposition pour description (métadonnée de Paramètre)

Renommage en label, ajout d'une limite de caractères et d'une contrainte d'unicité dans le système socio-fiscal.

Il s'agit d'une adaptation de la proposition 2B pour label (Variable), qui a été adoptée.

La liste des valeurs en doublon est disponible ci-dessous :

Nombre d'occurrences	Texte
47	Taux
23	Plafond
12	Indice majoré plafond
8	Maximum
7	Seuil
6	Cotisations et taxes des indépendants artisans-commerçants
5	Seuil de non versement
5	Plafond de ressources
5	'Taxes sur les salaires
4	Taux pour 2 enfants
4	Majoration du plafond pour les 2 premiers enfants
4	Majoration du plafond à partir du 3ème enfant
3	Taux pour une 3e personne
3	Taux pour une 2nde personne
3	Taux pour 2 adultes
3	Taux pour 1 enfant
3	Taux pour 1 adulte
3	Taux par personne supplémentaire
3	Taux de l'abattement
3	Taux 22%
3	Minimum
3	Limite d'âge des enfants comptés à charge
3	Effort à la construction
3	Cotisations syndicales
2	Zone 3 - couple
2	Zone 3 - Majoration par personne à charge supplémentaire
2	Zone 3 - Famille avec 1 personne à charge
2	Zone 3 - 1 adulte
2	Zone 2 - couple
2	Zone 2 - Majoration par personne à charge supplémentaire
2	Zone 2 - Famille avec 1 personne à charge
2	Zone 2 - 1 adulte
2	Zone 1 - couple
2	Zone 1 - Majoration par personne à charge supplémentaire
2	Zone 1 - Famille avec 1 personne à charge
2	Zone 1 - 1 adulte
2	Versement forfaitaire sur les salaires (1949-1967)
2	Taux pour les activités de ventes
2	Taux pour les activités de prestations et de services
2	Taux pour 4 enfants
2	Taux pour 3 enfants
2	Taux par enfants supplémentaires
2	Taux employé (de moins de 65 ans, en Alsace-Moselle) des cotisations de sécurité sociale (SS) des journalistes pigistes pour les assurances sociales avant 1967, sous le plafond de la sécurité sociale (PSS)
2	Taux de la majoration du RSA socle pour une femme enceinte sans enfant
2	Taux de la décote
2	Taux de la Contribution Sociale Généralisée (CSG) sur les revenus du capital (produits de placement)
2	Taux de la Contribution Sociale Généralisée (CSG) imposable sur les revenus d'activité
2	Taux de la Contribution Sociale Généralisée (CSG) déductible sur les revenus du capital (produits de placement)
2	Taux d'intérêt forfaitaire appliqué à l'épargne générant des revenus non imposables
2	Taux biens ruraux
2	Taux 30%
2	Taux 25%
2	Taux 2
2	Taux 18%
2	Taux 15%
2	Taux 1
2	Taux (WL)
2	Seuil de la décote pour un couple
2	Seuil de la décote pour un célibataire
2	Seuil de RFR à partir duquel un foyer ayant bénéficié d'un éco-prêt à taux zéro ne peut pas bénéficier du crédit d'impôt
2	Sécurité sociale/ Maladie, maternité
2	Sécurité sociale/ Indemnités journalières
2	Second plafond de ressources pour un enfant
2	Rsa socle
2	Revenus liés au patrimoine
2	Retraite de base
2	Retraite complémentaire
2	Report des excédents 2011
2	Réduction du temps de travail de 10%, allègements Robien (1996-2005) des cotisations de Sécurité sociale (SS)
2	Réduction d'impôt exceptionnelle
2	Prime de solidarité active
2	Premier taux
2	Pourcentage du RSA socle pour une personne (pour une personne)
2	Pourcentage du RSA socle pour trois personnes (pour trois et plus personnes)
2	Pourcentage du RSA socle pour deux personnes (pour deux personnes)
2	Plafond des dépenses
2	Plafond de ressources de base pour PAJE à taux plein
2	Plafond de ressources de base pour PAJE à taux partiel
2	Plafond de référence pour l'échelon 3, pour une famille avec un enfant,
2	Plafond de référence pour l'échelon 3, pour une famille avec 8 enfants
2	Plafond de référence pour l'échelon 3, pour une famille avec 7 enfants,
2	Plafond de référence pour l'échelon 3, pour une famille avec 6 enfants,
2	Plafond de référence pour l'échelon 3, pour une famille avec 5 enfants,
2	Plafond de référence pour l'échelon 3, pour une famille avec 4 enfants,
2	Plafond de référence pour l'échelon 3, pour une famille avec 3 enfants,
2	Plafond de référence pour l'échelon 3, pour une famille avec 2 enfants,
2	Plafond de référence pour l'échelon 2, pour une famille avec un enfant,
2	Plafond de référence pour l'échelon 2, pour une famille avec 8 enfants
2	Plafond de référence pour l'échelon 2, pour une famille avec 7 enfants,
2	Plafond de référence pour l'échelon 2, pour une famille avec 6 enfants,
2	Plafond de référence pour l'échelon 2, pour une famille avec 5 enfants,
2	Plafond de référence pour l'échelon 2, pour une famille avec 4 enfants,
2	Plafond de référence pour l'échelon 2, pour une famille avec 3 enfants,
2	Plafond de référence pour l'échelon 2, pour une famille avec 2 enfants,
2	Plafond de référence pour l'échelon 1, pour une famille avec un enfant,
2	Plafond de référence pour l'échelon 1, pour une famille avec 8 enfants
2	Plafond de référence pour l'échelon 1, pour une famille avec 7 enfants,
2	Plafond de référence pour l'échelon 1, pour une famille avec 6 enfants,
2	Plafond de référence pour l'échelon 1, pour une famille avec 5 enfants,
2	Plafond de référence pour l'échelon 1, pour une famille avec 4 enfants,
2	Plafond de référence pour l'échelon 1, pour une famille avec 3 enfants,
2	Plafond de référence pour l'échelon 1, pour une famille avec 2 enfants,
2	Pente du RSA
2	Participation des employeurs à la formation professionnelle continue (PEFPC), moins de 11 salariés
2	Par enfant à charge
2	Orphelin (de père et de mère), ou situation assimilée
2	Non mariés ou non PACS
2	Montant plafond par part pour les deux premières parts
2	Maximum par personne
2	Majoration pour biactifs et isolés, pour plafond taux plein
2	Majoration pour biactifs et isolés, pour plafond taux partiel
2	Majoration pour biactifs et isolés
2	Majoration du seuil par demi-part supplémentaire
2	Majoration du plafond pour le 1er enfant
2	Majoration du plafond pour biactifs ou isolé
2	Majoration du plafond par enfant supplémentaire
2	Majoration du plafond par enfant
2	Majoration du RSA socle pour parent isolé
2	Majoration du RSA socle par enfant supplémentaire (en pourcentage du
2	Loyer minimum lo
2	Limite de x % du revenu
2	Investissements locatifs intermédiaires
2	Investissements dans les DOM-TOM dans le cadre d'une entreprise
2	Invalidité, décès
2	Formation professionnelle
2	Forfait logement pour 3 personnes ou plus
2	Forfait logement pour 2 personnes
2	Forfait logement
2	Forfait annuel des cotisations pour l'association pour l'emploi des cades (APEC), régimes complémentaires de retraite (secteur privé)
2	Forfait Allocation de Soutien Familial
2	Fofait logement pour 1 personne (en % du rsa_socle)
2	Durée minimale de titre du séjour permettant de bénéficier du RSA
2	Cotisations salariales pour l'Association pour la gestion de la structure financière, ou cotisation ASF (1984-2001)
2	Cotisations retraite spécifiques à la fonction publique
2	Cotisations et taxes des professions libérales
2	Cotisations employeur de contribution au régime de garantie des salaires (AGS)
2	Cotisations de sécurité sociale (SS) pour les accidents du travail et les maladies professionnelles (AT-MP)
2	Cotisations de sécurité sociale (SS) des journalistes pigistes (1964-1974) pour les accidents du travail
2	Cotisations au régime de l'assurance chômage
2	Catégorie 1 / Autres régions - Plafonds de ressources annuelles imposables
2	Case XG
2	Case GU
2	Barème salarié des cotisations pour l'association pour l'emploi des cades (APEC), régimes complémentaires de retraite (secteur privé)
2	Allocation de base
2	Âge limite inférieur
2	Âge limite du benjamin pour un versement sans condition de durée
2	Âge de début de la 2ème majoration
2	Âge de début de la 1ere majoration
2	Activité de type BNC
2	Activité de type BIC
2	Activité de type Achat-Revente
2	Abattement maximum
2	Abattement appliqué sur la valeur locative des terrains non loués
2	Abattement appliqué sur la valeur locative des biens immobiliers non
2	1ère majoration pour âge
2	'Orphelin de père ou de mère (un seul parent manquant) ou situation assimilée
2	'Note 4
2	'Note 3
2	'Indemnité de résidence
2	"Indicatrice d'imposition"

Ces valeurs ont été obtenues par l'exécution de grep --no-filename -R 'label =' openfisca_france | cut -d '=' -f 2 | sort | uniq -c | sort .

En l'état, l'immense majorité des valeurs en doublon sont des termes génériques (« taux », « plafond »…).

En l'état, la description la plus longue compte 354 caractères.

---

• Nom :

- `description`
+ `label`

• Type :

- texte libre.
+ langage naturel limité à 420 caractères, sur une seule ligne, sans espace en début ni fin, unique dans le système socio-fiscal.

• Objet : donner un nom lisible au paramètre.
• Échelle de déclaration : Paramètre.
• Convention : contenir le nom de l'ensemble des nœuds traversés avec une expansion des abréviations et les abréviations entre parenthèses.
• Cas d'usage :
  • Désambiguer un paramètre dont le nom est une abréviation.
  • Rechercher et afficher un paramètre dans l'explorateur de législation.
• Exemples :
  • "Indicatrice d'imposition"
  • "Contribution exceptionnelle sur les hauts revenus"
• Lieu de documentation : openfisca.org/doc pour le format de données, CONTRIBUTING.md pour les conventions.

[MattiSG]

Version 1A d'une proposition pour reference (métadonnée de Paramètre)

On demande systématiquement un intitulé et une URL pour chaque référence législative, par le biais d'un dictionnaire plutôt que d'un tableau. Ceci a l'inconvénient d'alourdir la déclaration et suppose de normaliser la manière de référencer les URLs (i.e. de définir les clés du dictionnaire), et a l'avantage de traiter à la fois le cas d'usage pour le titre et l'URL de la reference.

Toutes les déclarations faites au niveau du nœud metadata sont déplacées vers le nœud parent (au même niveau que description, unit…)

Il s'agit d'une adaptation d'une série de propositions pour reference (Variable), qui a été adoptée.

---

• Nom : reference
• Type :

- texte libre, ou tableau de texte libre.
+ tableau associatif dont les clés sont des noms de textes légaux et les valeurs sont des URLs publiquement accessibles ou des chaînes vides.

• Objet : référence légale, identifier la loi de laquelle provient le paramètre.
• Échelle de déclaration : Paramètre.
• 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.
• Exemples :

- https://www.pole-emploi.fr/candidat/mes-droits-aux-aides-et-allocati/allocations-et-aides--les-repons/aides-financieres-aux-jeunes-dip.html
+   "Site Pôle Emploi": "https://www.pole-emploi.fr/candidat/mes-droits-aux-aides-et-allocati/allocations-et-aides--les-repons/aides-financieres-aux-jeunes-dip.html"

-    - "Décret n°2020-519 du 5 mai 2020: https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000041849630/"
-    - "Décret n°2020-769 du 24 juin 2020: https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000042032514"
-    - "Décret n°2020-1453 du 27 novembre 2020: https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000042574431"
+    Décret n°2020-519 du 5 mai 2020: "https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000041849630/"
+    Décret n°2020-769 du 24 juin 2020: "https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000042032514"
+    Décret n°2020-1453 du 27 novembre 2020: "https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000042574431"

[MattiSG]

Version 1A d'une proposition pour reference.href (métadonnée de Paramètre)

Plutôt qu'un nœud supplémentaire, on demande systématiquement un intitulé et une URL pour chaque référence législative, par le biais d'un dictionnaire. Ceci a l'avantage de traiter à la fois le cas d'usage pour le titre et l'URL de la reference.

Toutes les déclarations faites au niveau du nœud metadata sont déplacées vers le nœud parent (au même niveau que description, unit…) et transformées en reference tel que décrit dans la proposition 1A pour reference.

Il s'agit d'une adaptation d'une série de propositions pour reference (Variable), qui a été adoptée.

[MattiSG]

Version 1A d'une proposition pour reference.title (métadonnée de Paramètre)

Plutôt qu'un nœud supplémentaire, on demande systématiquement un intitulé et une URL pour chaque référence législative, par le biais d'un dictionnaire. Ceci a l'avantage de traiter à la fois le cas d'usage pour le titre et l'URL de la reference.

Toutes les déclarations faites au niveau du nœud metadata sont déplacées vers le nœud parent (au même niveau que description, unit…) et transformées en reference tel que décrit dans la proposition 1A pour reference.

Il s'agit d'une adaptation d'une série de propositions pour reference (Variable), qui a été adoptée.

[MattiSG]

Version 1A d'une proposition pour documentation (métadonnée de Paramètre)

Conserver la métadonnée telle quelle.

---

• Type : texte libre.
• Objet : explications générales, extension des acronymes, références législatives plus larges que des valeurs spécifiques.
• Échelle de déclaration : nœud metadata d'un Paramètre.
• Cas d'usage :
  • Ajouter une note en bas de chaque fichier Excel des barèmes IPP.
• Exemples :
  • À partir de 2014, des seuils spécifiques (célibataire, couple) sont employés pour le calcul de la décote.

Notes :
(i) La taxe d'apprentissage est créée par la Loi de finances du 13 juillet 1925.
La loi 77-704 du 05/07/1977créé une cotisation supplémentaire de 0,2% pour financer la formation en alternance; elle doit être versée de manière exceptionnelle en 1977.
Elle a été maintenue par la LFR pour 1978.
En 1990, la contribution supplémentaire de 0,10% est remplacée par une cotisation pérenne de 0,10% pour la formation en alternance.
(ii) Une incertitude subsiste sur le taux applicable en Alsace-Lorraine entre 1973 et 1978 inclus.
(iii) "La date d'effet correspond à la période de versement de la taxe. La taxe d'apprentissage et la CSA sont dues en N aux taux en vigueur en N sur les rémunérations versées en N.""
(iv) A l'heure actuelle (taxe payable en 2016, sur les rémunérations de 2015):
La taxe d'apprentissage et la CDA sont payées par toutes les entreprises assujetties à l'IR ou à l'IS; celles employant des apprentis en sont exonérées.
La CSA est due par les entreprises qui emploient moins d'un nombre-cible de "jeunes" et de travailleurs en alternance.
Le taux de CSA applicable varie à la fois avec la taille de l'entreprise et avec le pourcentage de salariés en alternance dans l'effectif annuel moyen de l'entreprise. Nous reportons ici uniquement le taux pour les entreprises de moins de 2000 salariés, dont les alternants, VIE et contrats CIFRE représentent moins de 1 % de l'effectif total de l'entreprise.
   Les autres taux sont, en 2019, de (art. 1609 quinvicies du CGI) :
   0,6 % (0,312 % en Alsace-Moselle) si le nombre de salariés titulaires d'un contrat de professionnalisation ou d’apprentissage et de jeunes accomplissant un VIE ou bénéficiant d'une CIFRE est inférieur à 1 % de l'effectif annuel moyen et si l'effectif total est supérieur à 2000 salariés ;
   0,2 % (0,104 % en Alsace-Moselle) si le nombre de salariés et de jeunes appartenant aux catégories susvisées est compris entre 1 et 2 % de l’effectif annuel moyen ;
   0,1 % (0,052 % en Alsace-Moselle) si le nombre de salariés et de jeunes appartenant aux catégories susvisées est compris entre 2 et 3 % de l’effectif annuel moyen ;
   0,05 % (0,026 % en Alsace-Moselle) si le nombre de salariés et de jeunes appartenant aux catégories susvisées est compris entre 3 et 5 % de l’effectif annuel moyen.
Sources :
Taxe d'apprentissage : CGI, art. 224 et s. et art. 140 A et s. de l'annexe I ; pour l'Alsace-Moselle, art. 1599 ter J.
CSA : CGI, art. 230 H puis (à partir de 2014, cf. Décret 2014-549, JO 2014-05-29) 1609 quinvicies

[MattiSG]

Version 1B d'une proposition pour documentation (métadonnée de Paramètre)

Abandonner l'ajout d'une telle métadonnée dans OpenFisca et privilégier l'usage des commentaires plutôt que d'une métadonnée dédiée pour les hypothèses d'implémentation, car celles-ci sont associées à l'implémentation (au code).

Pour le cas d'usage et exemples donnés (insérer une note dans les barèmes IPP), soit passer par une base de données externe à OpenFisca, soit générer les notes par l'extraction des commentaires, comme le permet par exemple ruamel.yaml.

Il s'agit de la proposition 1B pour Notes (métadonnée de variable), qui a été adoptée.

[Sasha-Laniece]

Bonjour @MattiSG , je ne vois pas les champs ux_name et last_review qui ont déjà été votés au printemps ? Tu confirmes que c'est parce qu'ils sont déjà acquis ? @sandcha @DorineLam @benoit-cty @benjello

[MattiSG]

Sont encore en attente de rédaction :

• date_parution_jo
• unit (et threshold_unit, rate_unit, amount_unit pour les barèmes)
• description_en
• ux_name
• last_review

[Sasha-Laniece]

Hello à tous, Pour rassembler tous les éléments sur cette issue, et notamment les motivations des premières décisions, voici le lien de la toute première RFC du printemps (celle que vous avez vue à l'époque sur Slack #france-system): https://github.com/openfisca/openfisca-france/issues/1519 Le débat en cours ici est maintenant bien plus avancé, et clairement sur la forme c'était pas top, à l'époque on avait grandement besoin des compétences de @MattiSG ^^

[MattiSG]

Version 1A d'une proposition pour date_parution_jo (métadonnée de Paramètre)

Renommer les occurrences de official_journal_date en dates_journal_officiel, en les laissant dans le nœud metadata. Transformer les valeurs en un tableau de dates afin de gérer les références multiples.

Cela implique que l'ordre des références est signifiant. Cela semble pouvoir être garanti en chargeant le YAML avec Python. Cela implique également une charge cognitive car l'ordre de déclaration des références doit correspondre à l'index des dates_journal_officiel. Ceci est contre-intuitif pour un dictionnaire.

---

• Nom :

- official_journal_date
- date_parution_jo
+ dates_journal_officiel

• Type :

- date
+ tableau de dates

• Objet :

- date de publication au JO (et non date d'effet) du ou des textes de loi référencés dans `reference:title` et `reference:href`.
+ dates de publication au JO (et non date d'effet) des textes de loi de la `reference`.

• Échelle de déclaration : nœud metadata d'un Paramètre.
• Cas d'usage :
  • Identifier la loi de laquelle provient le paramètre.
• Exemples :

- 2019-01-01: 2018-09-06
+ dates_journal_officiel: [ 2018-09-06 ]
- 2014-01-01: 2013-12-29; 2012-03-15
+ dates_journal_officiel: [ 2013-12-29, 2012-03-15 ]

• Lieu de documentation : CONTRIBUTING.md (pas de normalisation dans Core).

[MattiSG]

Version 1B d'une proposition pour date_parution_jo (métadonnée de Paramètre)

Renommer les occurrences de official_journal_date en parutions_journal_officiel, en les laissant dans le nœud metadata. Le terme « date » n'a pas à apparaître dans le nom de la métadonnée puisque le type de valeur permet de l'inférer. Transformer les valeurs en un dictionnaire de dates dont les clés doivent correspondre aux clés de reference afin de gérer les références multiples.

Cela implique la duplication des clés dans reference et dans parutions_journal_officiel. Un validateur automatique de l'identité entre les deux groupes de clé pourra aider.

---

• Nom :

- official_journal_date
- date_parution_jo
+ parutions_journal_officiel

• Type :

- date
+ dictionnaire dont les clés sont les mêmes que celles de la `reference`, et les valeurs sont des dates

• Objet :

- date de publication au JO (et non date d'effet) du ou des textes de loi référencés dans `reference:title` et `reference:href`.
+ dates de publication au JO (et non date d'effet) des textes de loi de la `reference`.

• Échelle de déclaration : nœud metadata d'un Paramètre.
• Cas d'usage :
  • Identifier la loi de laquelle provient le paramètre.
• Exemples :

- 2019-01-01: 2018-09-06
+ parutions_journal_officiel:
+   Décret du 6 septembre 2018: 2018-09-06
- 2014-01-01: 2013-12-29; 2012-03-15
+ parutions_journal_officiel:
+   Circulaire ministérielle du 29 décembre 2013: 2013-12-29
+   Loi Mirlade: 2012-03-15

• Lieu de documentation : CONTRIBUTING.md (pas de normalisation dans Core).

[MattiSG]

Version 1C d'une proposition pour date_parution_jo (métadonnée de Paramètre)

Abandonner l'ajout d'une telle métadonnée dans OpenFisca, car l'information de date de publication peut être stockée dans l'intitulé de reference et obtenue automatiquement depuis l'URL de reference, et que la valeur ajoutée pour désambiguer n'est pas claire. En particulier, la gestion des reference multiples ajoute une complexité significative à date_parution_jo.

[MattiSG]

Version 1A d'une proposition pour description_en (métadonnée de Paramètre)

Renommage en label_en, ajout d'une limite de caractères et d'une contrainte d'unicité dans le système socio-fiscal.

---

• Nom :

- description_en
+ label_en

• Type :

- texte libre (anglais)
+ langage naturel en anglais limité à 420 caractères, sur une seule ligne, sans espace en début ni fin

• Objet : nom du paramètre en anglais.
• Échelle de déclaration : nœud metadata d'un Paramètre.
• Cas d'usage :
  • Générer la version anglaise du site de l'IPP.
• Exemples :
  • Apprenticeship tax (tax for the financing of apprenticeship)
  • Other payroll and workforce taxes
• Lieu de documentation : CONTRIBUTING.md (pas de normalisation dans Core).

[MattiSG]

Version 1B d'une proposition pour description_en (métadonnée de Paramètre)

Gestion multilingue optionnelle des label : la clé label peut être un dictionnaire qui contient pour clé un code ISO de langue et pour valeur la description du paramètre dans la langue désignée. Une valeur par défaut est définie à l'échelle du système socio-fiscal, qui est attribuée en l'absence de clé explicite. Une limite de caractères et une contrainte d'unicité dans le système socio-fiscal sont ajoutées pour toutes les langues.

---

• Nom :

- description_en
+ label

• Type :

- texte libre (anglais)
+ dictionnaire dont les clé sont des codes ISO régionaux, et les valeurs sont des chaînes de caractère en langage naturel dans la langue indiquée par la clé, limitées à 420 caractères, sur une seule ligne, sans espace en début ni fin

• Objet :

- nom du paramètre en anglais.
+ nom du paramètre dans une autre langue.

• Échelle de déclaration :

- nœud `metadata` d'un Paramètre
+ Paramètre

• Cas d'usage :
  • Générer la version anglaise du site de l'IPP.
• Exemples :

- Apprenticeship tax (tax for the financing of apprenticeship)
+ label:
+   fr: Taxe d'apprentissage
+   en: Apprenticeship tax (tax for the financing of apprenticeship)

- Other payroll and workforce taxes
+ label:
+   fr: Taxes et participations
+   en: Other payroll and workforce taxes

• Lieu de documentation : Core.

[MattiSG]

Version 1C d'une proposition pour description_en (métadonnée de Paramètre)

Abandonner l'ajout d'une telle métadonnée dans OpenFisca, car les cas d'usage sont trop spécifiques. Les implémenteurs peuvent constituer leur propre base de traduction en dehors d'OpenFisca, en associant le nom du Paramètre avec ses traductions dans les langues souhaitées.

[MattiSG]

Version 1A d'une proposition pour last_reviewed (métadonnée de Paramètre)

Abandonner l'ajout d'une telle métadonnée dans OpenFisca, en raison de l'impossibilité de donner du sens à une date de revue.

Les informations de relecture pourraient faire l'objet d'un traitement dans un outil tiers, qui associerait un identifiant OpenFisca à un nombre arbitraire d'auditeurs qui pourraient indiquer leur validation de l'identifiant, la date, et le numéro de version du système socio-fiscal qui a fait l'objet de la validation.

Il s'agit d'une adaptation de la proposition 1B pour last_reviewed (Variable), qui a été adoptée.

[MattiSG]

Version 1A d'une proposition pour ux_name (métadonnée de Paramètre)

On introduit une métadonnée dédiée short_label en considérant que le besoin d'un nom non-ambigu avec un nombre connu de caractères est suffisamment répandu. On suppose qu'un contexte de présentation permettra de différencier entre deux paramètres ayant le même short_label.

Il s'agit d'une adaptation de la proposition 1A pour ux_name (Variable), qui a été adoptée.

• Nom :

- ux_name
+ short_label

• Type :

- texte libre avec un nombre court de caractères.
+ langage naturel limité à 70 caractères, sur une seule ligne, sans espace en début ni fin.

• Objet : nom court du paramètre, autorisant les abréviations les plus connues.
• Échelle de déclaration :

- nœud `metadata` d'un Paramètre
+ Paramètre

• Cas d'usage :
  • Afficher un nom reconnaissable par une personne non experte du modèle OpenFisca dans un espace d'affichage connu d'avance.
  • Faciliter la construction d'interfaces graphiques en ayant une contrainte connue de taille d'affichage.
• Exemples :
  • Taxes et participations
  • Fonds national d'aide au logement (FNAL)
• Lieu de documentation : openfisca.org/doc (les cas d'usage mentionnés nécessitent d'exposer cette information dans l'API web, il faudra donc modifier Core). Afin de supporter des langues différentes, le nombre et le type de caractères autorisés pourra faire l'objet d'une spécification par pays. La limite sera donc documentée dans CONTRIBUTING.md. Les conventions de rédaction (quels acronymes étendre…) seront documentées dans le CONTRIBUTING.md.

[MattiSG]

Version 1A d'une proposition pour unit (métadonnée de Paramètre)

On normalise les valeurs possibles pour cette métadonnée, et on la bascule dans le nœud metadata dans la mesure où il n'y a à ce stade aucun impact fonctionnel à son remplissage. Les valeurs possibles sont décrites à la fois dans Core (currency, percentage…) et dans France (SMIC, PSS…).

Comme aujourd'hui, les changements d'unité dans un seul paramètre ne sont pas permis : en cas de changement de monnaie, par exemple, deux paramètres distincts devront être introduits.

---

• Nom : unit
• Type :

- texte libre
+ enum

• Objet : décrire l'unité dans laquelle doit être interprétée la valeur déclarée.
• Échelle de déclaration :

- Paramètre
+ nœud `metadata` d'un Paramètre

• Cas d'usage :
  • Afficher l'unité dans l'explorateur de législation.
  • Éviter d'indiquer l'unité en texte libre dans le champ description.
• Exemples :

- unit: currency
+ metadata:
+   unit: currency

- unit: /1
+ metadata:
+   unit: percentage

• Lieu de documentation : openfisca.org/doc pour l'usage et la liste des types de base. Afin de supporter des unités spécifiques (valeur du SMIC, montant du plafond de la sécurité sociale…), les types spécifiques à la France seront déclarés dans OF-France.

[MattiSG]

Version 1B d'une proposition pour unit (métadonnée de Paramètre)

On normalise les valeurs possibles pour cette métadonnée, et on la bascule au même niveau que value pour permettre les changements d'unité dans une seule déclaration de paramètre. Les valeurs possibles sont décrites à la fois dans Core (currency, percentage…) et dans France (SMIC, PSS…).

Cette proposition permet de gérer les changements d'unité, un cas connu étant le changement de monnaie (FRF → EUR), au prix d'une forte répétition de la déclaration des unités.

---

• Nom : unit
• Type :

- texte libre
+ enum

• Objet : décrire l'unité dans laquelle doit être interprétée la valeur déclarée.
• Échelle de déclaration :

- Paramètre
+ nœud de date de valeur d'un Paramètre

• Cas d'usage :
  • Afficher l'unité dans l'explorateur de législation.
  • Éviter d'indiquer l'unité en texte libre dans le champ description.
• Exemples :

- unit: currency
+ values:
+   2019-01-01:
+     unit: currency

- unit: /1
+ values:
+   2019-01-01:
+     unit: percentage

• Lieu de documentation : openfisca.org/doc pour l'usage et la liste des types de base. Afin de supporter des unités spécifiques (valeur du SMIC, montant du plafond de la sécurité sociale…), les types spécifiques à la France seront déclarés dans OF-France.

[MattiSG]

Version 1C d'une proposition pour unit (métadonnée de Paramètre)

Abandonner l'ajout d'une telle métadonnée, car elle n'a toujours pas à ce stade trouvé d'usage fonctionnel. Si l'interprétation est ambigüe, il est toujours possible de l'indiquer par un commentaire dans le code ou dans la description du Paramètre. C'est d'ailleurs le plus souvent déjà le cas aujourd'hui.

[MattiSG]

Version 1A d'une proposition pour threshold_unit (métadonnée de Paramètre)

On normalise les valeurs possibles pour cette métadonnée. Les valeurs possibles sont décrites à la fois dans Core (currency, percentage…) et dans France (SMIC, PSS…), et sont les mêmes que pour la métadonnée unit.

Comme aujourd'hui, les changements d'unité dans un seul paramètre ne sont pas permis : en cas de changement de monnaie, par exemple, deux paramètres distincts devront être introduits.

---

• Nom : threshold_unit
• Type :

- texte libre
+ enum

• Objet : décrire l'unité dans laquelle doit être interprétée la valeur déclarée.
• Échelle de déclaration :

- Paramètre
+ nœud `metadata` d'un Paramètre

• Cas d'usage :
  • Afficher l'unité dans l'explorateur de législation.
  • Éviter d'indiquer l'unité en texte libre dans le champ description.
• Exemples :
  • threshold_unit: currency

- threshold_unit: /1
+ threshold_unit: percentage

• Lieu de documentation : openfisca.org/doc pour l'usage et la liste des types de base. Afin de supporter des unités spécifiques (valeur du SMIC, montant du plafond de la sécurité sociale…), les types spécifiques à la France seront déclarés dans OF-France.

[MattiSG]

Version 1B d'une proposition pour threshold_unit (métadonnée de Paramètre)

On normalise les valeurs possibles pour cette métadonnée, et on la bascule au même niveau que value pour permettre les changements d'unité dans une seule déclaration de paramètre. Elle est de fait renommée en unit puisque le contexte d'interprétation (threshold ou rate) peut être lu dans la hiérarchie de déclaration. Les valeurs possibles sont décrites à la fois dans Core (currency, percentage…) et dans France (SMIC, PSS…), et sont les mêmes que pour la métadonnée unit.

---

• Nom :

- threshold_unit
+ unit

• Type :

- texte libre
+ enum

• Objet : décrire l'unité dans laquelle doit être interprétée la valeur déclarée.
• Échelle de déclaration :

- nœud metadata d'un Paramètre
+ nœud de date de valeur d'un threshold de barème d'un Paramètre

• Cas d'usage :
  • Afficher l'unité dans l'explorateur de législation.
  • Éviter d'indiquer l'unité en texte libre dans le champ description.
• Exemples :

- metadata:
-   threshold_unit: SMIC
+ threshold:
+    1967-10-01:
+      unit: SMIC

- metadata:
-   threshold_unit: /1
+ threshold:
+   1984-04-01:
+     unit: percentage

• Lieu de documentation : openfisca.org/doc pour l'usage et la liste des types de base. Afin de supporter des unités spécifiques (valeur du SMIC, montant du plafond de la sécurité sociale…), les types spécifiques à la France seront déclarés dans OF-France.

[MattiSG]

Version 1C d'une proposition pour threshold_unit (métadonnée de Paramètre)

Abandonner l'ajout d'une telle métadonnée, car elle n'a toujours pas à ce stade trouvé d'usage fonctionnel et est peu renseignée dans la base de code actuelle. Si l'interprétation est ambigüe, il est toujours possible de l'indiquer par un commentaire dans le code ou dans la description du Paramètre. C'est d'ailleurs le plus souvent déjà le cas aujourd'hui.

[MattiSG]

Version 1A d'une proposition pour rate_unit (métadonnée de Paramètre)

On normalise les valeurs possibles pour cette métadonnée. Les valeurs possibles sont décrites à la fois dans Core (currency, percentage…) et dans France (SMIC, PSS…), et sont les mêmes que pour la métadonnée unit.

Comme aujourd'hui, les changements d'unité dans un seul paramètre ne sont pas permis : en cas de changement de monnaie, par exemple, deux paramètres distincts devront être introduits.

---

• Nom : rate_unit
• Type :

- texte libre
+ enum

• Objet : décrire l'unité dans laquelle doit être interprétée la valeur déclarée.
• Échelle de déclaration :

- Paramètre
+ nœud `metadata` d'un Paramètre

• Cas d'usage :
  • Afficher l'unité dans l'explorateur de législation.
  • Éviter d'indiquer l'unité en texte libre dans le champ description.
• Exemples :
  • rate_unit: currency

- rate_unit: /1
+ rate_unit: percentage

• Lieu de documentation : openfisca.org/doc pour l'usage et la liste des types de base. Afin de supporter des unités spécifiques (valeur du SMIC, montant du plafond de la sécurité sociale…), les types spécifiques à la France seront déclarés dans OF-France.

[MattiSG]

Version 1B d'une proposition pour rate_unit (métadonnée de Paramètre)

On normalise les valeurs possibles pour cette métadonnée, et on la bascule au même niveau que value pour permettre les changements d'unité dans une seule déclaration de paramètre. Elle est de fait renommée en unit puisque le contexte d'interprétation (threshold ou rate) peut être lu dans la hiérarchie de déclaration. Les valeurs possibles sont décrites à la fois dans Core (currency, percentage…) et dans France (SMIC, PSS…), et sont les mêmes que pour la métadonnée unit.

---

• Nom :

- rate_unit
+ unit

• Type :

- texte libre
+ enum

• Objet : décrire l'unité dans laquelle doit être interprétée la valeur déclarée.
• Échelle de déclaration :

- nœud metadata d'un Paramètre
+ nœud de date de valeur d'un rate de barème d'un Paramètre

• Cas d'usage :
  • Afficher l'unité dans l'explorateur de législation.
  • Éviter d'indiquer l'unité en texte libre dans le champ description.
• Exemples :

- metadata:
-   rate_unit: SMIC
+ rate:
+   1967-10-01:
+     unit: SMIC

- metadata:
-   rate_unit: /1
+ rate:
+   1984-04-01:
+     unit: percentage

• Lieu de documentation : openfisca.org/doc pour l'usage et la liste des types de base. Afin de supporter des unités spécifiques (valeur du SMIC, montant du plafond de la sécurité sociale…), les types spécifiques à la France seront déclarés dans OF-France.

[MattiSG]

Version 1C d'une proposition pour rate_unit (métadonnée de Paramètre)

Similaire à la proposition 1A, mais on renomme en unit en considérant que l'interprétation la moins ambigüe d'une « unité » pour un barème est d'abord celle de sa valeur, ce qui réduit le nombre de métadonnées à connaître.

---

• Nom :

- rate_unit
+ unit

• Type :

- texte libre
+ enum

• Objet : décrire l'unité dans laquelle doit être interprétée la valeur déclarée.
• Échelle de déclaration :

- Paramètre
+ nœud `metadata` d'un Paramètre

• Cas d'usage :
  • Afficher l'unité dans l'explorateur de législation.
  • Éviter d'indiquer l'unité en texte libre dans le champ description.
• Exemples :

- rate_unit: currency
+ unit: currency

- rate_unit: /1
+ unit: percentage

• Lieu de documentation : openfisca.org/doc pour l'usage et la liste des types de base. Afin de supporter des unités spécifiques (valeur du SMIC, montant du plafond de la sécurité sociale…), les types spécifiques à la France seront déclarés dans OF-France.

[MattiSG]

Version 1D d'une proposition pour rate_unit (métadonnée de Paramètre)

Abandonner l'ajout d'une telle métadonnée, car elle n'a toujours pas à ce stade trouvé d'usage fonctionnel et est peu renseignée dans la base de code actuelle. Si l'interprétation est ambigüe, il est toujours possible de l'indiquer par un commentaire dans le code ou dans la description du Paramètre. C'est d'ailleurs le plus souvent déjà le cas aujourd'hui.

[MattiSG]

Sauf erreur de ma part, toutes les métadonnées à traiter sont listées ! Cela ne signifie pas que toutes les propositions possibles ont été faites, vous êtes comme toujours bienvenu‧e‧s pour en établir de nouvelles 👍

Désolé pour le délai dans la rédaction 😞 le travail nécessaire sur unit en particulier était non négligeable et j'ai trop traîné à bloquer un créneau suffisant pour le traiter.

Comme indiqué dans #1618, dont cette PR découle, cette RFC sera ouverte jusqu'à ce que le jeu de propositions soit resté stable pendant 14 jours.

[Sasha-Laniece]

Version 1A d'une proposition pour reference (métadonnée de Paramètre)

On demande systématiquement un intitulé et une URL pour chaque référence législative, par le biais d'un dictionnaire plutôt que d'un tableau. Ceci a l'inconvénient d'alourdir la déclaration et suppose de normaliser la manière de référencer les URLs (i.e. de définir les clés du dictionnaire), et a l'avantage de traiter à la fois le cas d'usage pour le titre et l'URL de la reference.

Toutes les déclarations faites au niveau du nœud metadata sont déplacées vers le nœud parent (au même niveau que description, unit…)

Il s'agit d'une adaptation d'une série de propositions pour reference (Variable), qui a été adoptée.

Hello ! N'avions-nous pas aussi parlé de la possibilité de mettre la référence (title et href) au niveau de value ? C'est déjà fait comme cela dans certains paramètres