feat: enable schema extensions via data package architecture

[ttdm]

/!\ ne pas merge cette PR les données utilisées pour générer les schémas sont des illustratives permettant de vérifier le bon fonctionnement du code proposé

Génération automatique des schémas par combinaison core + extensions

Cette PR introduit une architecture modulaire pour la génération des schémas du dispositif d'aide.

Principe
Le schéma est désormais découpé en :

• un core (schema/core/schema-core.json) contenant les champs communs à tous les schémas
• des extensions organisées par catégorie (schema/extensions/cible/ et schema/extensions/usage/) contenant les champs spécifiques à une cible ou un usage

Un script de build (src/build_schemas.py) génère automatiquement toutes les combinaisons core × cible × usage et produit les schémas finaux dans build/schemas/.

Ce que ça change concrètement

• Pour ajouter ou modifier un champ : on édite uniquement le fichier source concerné (core ou extension), et les schémas sont regénérés automatiquement
• GitHub Actions prend en charge la génération et la validation à chaque push modifiant schema/
• Un guide d'utilisation est disponible dans DEVELOPMENT.md

Structure des sources
schema/ => Contient uniquement des fichiers json permettant de créer des schéma valides en se combinant les uns les autres
Build/ => Dossier autogénéré comprennant toutes les combinaisons de json schema valides
src/ => Contient quelques fichiers sources permettant 1/de générer les schéma 2/ de gérer les conflits 3/ de valider les schémas générés

Note : tout ce qui se trouve dans build/ est auto-généré — ce dossier n'est pas à review.

[ttdm]

/!\ ne pas merge cette PR

Salut @Pierlou ,

La PR est prête à être review.
La proposition technique est faite, les données des champs, en particulier sur les extensions ne sont pas bonnes pour illustrer le bon fonctionnement tech.

Tests réalisés :

• json non conformes -> la validation frictionless break correctement
• champs non conformes à leur description -> la validation frictionless break correctement
• générations de multiples cibles/usage -> présence d'un fichier schema et d'un fichier d'exemple pour chaque combinaison géérée. Toutes les combinaisons attendues sont correctement générées
• sur les conflits entre champs : même nom de champ avec type différent -> le schéma final prend un élément au hasard et reporte une erreur dans les logs
• Même nom de champs et même type dans plusieurs (>2) schéma qui se combinent -> vérification manuelle que les sont contraintes correctement additionnées.

[Pierlou]

Thanks a lot for this huge refactor! Most comments are syntax/wording suggestions. Also not sure about the workflow around the datapackage file
Also for fields names, descriptions and typing, it'd be nice to have a review from people who actually know the topic 🙏

[ttdm]

Merci pour la review. Ta précédente review était en francais, c'est une volonté d'etalab de passer en anglais ?

Comme indiqué dans le 2nd message, les champs schémas ne sont pas à review car illustratifs pour montrer le fonctionnement de la partie technique. Il seront supprimés avant de merge. Je me suis donc permis de clore les messages liés.

Merci pour les suggestions sur la quasi totalité des autres commentaires que j'ajouterai demain à la PR.

Le seul point restant serait celui-çi :

I'm confused: if this repo is going to be a datapackage, then resources should be the list of all sub-schemas right? (cf the template)

Effectivement, actuellement, le repo ne génère pas un datapackge mais une collection de table-schema.json => https://specs.frictionlessdata.io/schemas/table-schema.json indépendants.

Quand je vois le fichier que tu as link, je me rend compte que je n'avais pas du tout en tête la bonne définition d'un datapackage et c'est ce qui explique que j'avais abandonné cette solution.
A la lecture de ton fichier, j'ai l'impression que je peux laisser le format actuel pour chaque sous schéma et simplement générer un fichier supplémentaire datapackage.json à la recine qui pointe simplement vers l'ensemble des autres fichiers. ça te semble cohérent et ça te semblerait satisfaisant comme cela ?

[Pierlou]

Désolé pour la review en anglais, on a l'habitude de faire ça dans le pôle data (même si ce dont on parle est franco-français) je ne me suis pas posé la question 😅
Pour le datapackage : schema.data.gouv ne s'interface actuellement qu'avec :

• un repo qui contient un schema.json (pour les TableSchemas)
• un repo qui contient un datapackage.json pour les datapackages (plusieurs TableSchemas liés)
• (d'autres structures pour des données non tabulaires donc non pertinentes pour le cas présent)

Ce repo étant voué à accueillir plusieurs TableSchemas, c'est le second point qui me semble adapté. La structure attendue est dans le lien que j'ai donné, pour un rendu similaire à ceci (un sous-menu qui expose les différents schémas, ce qui évite de surcharger la page d'accueil avec beaucoup de schémas liés à un seul sujet). Les modifs pour arriver à cela me semblent assez légères, le très gros du travail a déjà été fait 💪

[ttdm]

I can switch to English, that’s not a problem.
I initially stuck to French to stay consistent, but now that we’re 50/50 in the thread, we can have a bit of fun switching between the two :)

Thanks a lot for your review and for the link to the datapackage.json example — it’s much clearer to me now what was expected.
I’ve made all the requested changes: built a proper datapackage, switched back to proper table-schema for all schemas, updated the validator accordingly, and clarified a couple of core methods now that the target architecture is much clearer to me.

Everything should be back in a reviewable state. I expect this PR to be closer to the final result, but please feel free to nitpick if you see further improvements.

Out of curiosity, what did you mean by “d'autres structures pour des données non tabulaires donc non pertinentes pour le cas présent”? When we chose table-schema a year ago, one of the main arguments was that it was best supported by schema.data.gouv and publier.etalab. I’d be interested to know what other options were available then, or what you would recommend now.

[Pierlou]

I'll try to review the changes next week, thanks for the quick fixes/improvements!
The other two formats we currently support are:

• JSONSchema, for treelike data
• "Other" which we use to reference standards that don't match any of the other types (many CNIG standards for instance), because the goal is to centralize as many as possibe, even though they're structured differently

datagouv is very muh turned towards tabular data, we have a bunch of automatic processes around them (column content detection, APIfication, conversions into other formats...) so a TableSchema for this use case felt like the best option

[Pierlou]

Looks good to me! 👏 Again, I'd be happy to have someone else review this, ideally someone who'll be using it
Once this is done we can merge, create a release, and see what it looks like on our preprod platform

[David-Guillot]

Bon ça y est @ttdm j'ai enfin eu du temps pour me plonger dans cette PR en étant pleinement concentré sur le sujet. Ce que je peux en dire :

• La structure me semble parfaite ! Combiner les extensions par cibles et par usages va permettre de réaliser ce dont on parle depuis des mois, c'est vraiment top !
• Le workflow d'évolution des schémas me semble à l'avenant, c'est-à-dire très propre ! Les schémas sources sont DRY, et rien ne repose sur des manips manuelles pour mettre à jour les schémas réels
• Je ne sais pas trop où on sont les retours concernant les remarques formulées par Pierlou : certains commentaires ont été marqués comme résolus mais je ne vois ni modification de code ni justification du code qui a fait l'objet du commentaire ; je pense à l'histoire des champs date vs datetime par exemple, ou à l'usage pas assez systématique du français pour la documentation
• Le code Python qui réalise la fusion des schémas n'est pour l'instant couvert par aucun test, ça me paraît un peu casse-gueule, d'autant que l'algo prend des décisions de résolution de conflit que des tests automatisés aideraient à comprendre et maintenir dans le temps

Merci pour tout ce travail, on en parle demain.

Sans lien direct avec cette PR mais en lien avec ce schéma, en ce qui me concerne après une première implémentation d'une API en écriture basée sur le schéma cœur, j'ai un gros grief sur notre choix, dont je doutais déjà à l'époque, du champ porteurs_aide qui est une string contenant un JSON qui doit ensuite être parsé... C'est vraiment beaucoup de complexité technique dans le seul but de minimiser le nombre de champs... À discuter !

[ttdm]

@David-Guillot
Je pense avoir répondu à la totalité des remarques de Pierlou qui concernent cette PR mais pour les quelques points que tu relèves, je peux préciser :

• Pour les dates, il s'agit de la reprise du format actuel. Il n'y a, dans cette PR, aucune modification effectuée sur le schéma coeur. Je n'ai rien contre modifier mais c'est bien une modif supplémentaire par rapport à l'existant et je serais d'avis de faire ça dans une autre PR pour des raisons de lisibilité de l'historique du schéma. Il y a une issue ouverte sur les évolutions / corrections possibles à apporter au schéma coeur. Il me semble que ça pourrait aller dedans. J'aurai effectivement du répondre à ce commentaire plutôt que de le clore.
• J'ai relu tous les commentaires et je ne comprend pas ta deuxième remarque sur l'usage du francais. Pour moi les seuls autres commentaires que je n'ai pas traités sont les commentaires qui concernent les fichiers jsons qui sont présent dans cibles et/ou dans usage et qui sont à supprimer avant merge car servant uniquement à illustrer le fonctionnement tech comme expliqué dans plusieurs de mes messages. Je veux bien un ping précis si j'ai raté un message :)

Sur le format choisi, de mon point de vue la question n'était pas sur minimiser le nombre de champ mais sur un format tabulaire vs non-tabulaire, la PR a été l'occasion d'en rediscuter rapidement avec Pierlou et je renvoie vers ce message : #7 (comment)
J'ai aussi des doutes sur ce choix mais je ne suis pas sur qu'on puisse faire autrement sauf à ne plus/moins utiliser d'outils datagouv.

Sur les tests, je suis tout à fait d'accord. C'est une de mes faiblesses en tant que dev en général. J'ai très souvent l'impression que les tests que j'écris sont trop triviaux pour être intéressants. Tu aurais le temps de proposer quelque chose ?

[Pierlou]

Pour le format tabulaire : ce n'est pas obligatoire, datagouv met mieux en valeur ce format que les autres (prévisualisation, APIfication, conversion dans d'autres formats...), mais il reste tout à fait possible de publier des données dans d'autres formats, notamment le JSON. Si vous voulez creuser dans cette direction, il est possible de formaliser un JSONSchema

[David-Guillot]

@ttdm OK j'ai compris que les commentaire de Pierlou sur lesquels j'avais focalisé concernent des fichiers qui n'avaient pas vocation à être commités. En fait, ce que je vais faire, c'est déplacer des choses dans un répertoire de tests, et réutiliser les schémas sources et build que tu qualifies d'illustratifs et temporaires, et en faire un jeu de tests (source => fixture, et build => expected).

[David-Guillot]

Ok @ttdm merci pour la review de ma PR, tu es même allé plus loin que ce que je pensais vu que tu as résolu les inévitables problèmes liés à un workflow Github qu'on n'a pas pu tester avant 👍 (je pensais qu'on allait itérer ensemble sur ce sujet après que le premier run soit passé, merci d'avoir pris ça en charge).

J'ai une question sur ton dernier commit, mais elle n'est pas bloquante pour la validation finale : je suis étonné de voir que le contenu de build/schemas et build/exemples a été commité en même temps que tout le reste, par toi, et non pas par le workflow Github ; c'est normal ?

En dehors de cette question, pour moi en l'état on est OK pour envoyer tout ça 👍

[ttdm]

Ok @ttdm merci pour la review de ma PR, tu es même allé plus loin que ce que je pensais vu que tu as résolu les inévitables problèmes liés à un workflow Github qu'on n'a pas pu tester avant 👍 (je pensais qu'on allait itérer ensemble sur ce sujet après que le premier run soit passé, merci d'avoir pris ça en charge).

Très franchement j'avais un peu honte de la source de l'erreur. Je pense que c'est du code qui ne va pas beaucoup bouger et rester relativement simple, d'où les libertés que j'ai pris sur un certain nombre de bonne pratique. Mais quand j'ai vu que l'erreur venait d'une path codée en statique à 2 endroits différents, je me suis dis que ça valait le coup d'améliorer un peu cela !

J'ai une question sur ton dernier commit, mais elle n'est pas bloquante pour la validation finale : je suis étonné de voir que le contenu de build/schemas et build/exemples a été commité en même temps que tout le reste, par toi, et non pas par le workflow Github ; c'est normal ?

Les deux sont possibles, commit manuels et commit via le workflow. La seule différence c'est de lancer le script de build en local ou via le workflow. Comme j'étais sur le code et que j'étais en train de fix le script de build, je l'ai fait en local pour vérifier que ma proposition était bien fonctionnelle. (Ton erreur au build que j'ai fix éxistait aussi lorsque que tu lancais le script en local par exemple.)
Le fait que le workflow n'ajoute pas de commit est aussi plutôt positif. On a un process identique sur TEE et généralement, lorsqu'il n'y a pas de commit, c'est parce que le workflow génère les mêmes fichiers et ne détecte pas de changements !

@Pierlou On est donc tout bon, tu peux merge !