# Dictionnaire central des champs

> **En bref :**
> Annexe de référence pour la DSI : le trajet de chaque champ, de l'annuaire au graphe, puis à l'API Apollo et à SoVisu+.
> Plusieurs champs n'atteignent pas le graphe : type d'appartenance, HDR, dates d'affiliation. Les **emails** n'y entrent pas non plus, mais **SoVisu+ les conserve** dans sa propre base.
> Ce qui est publiable en vitrine n'est pas décidé ici : la matrice des champs fait foi dans la page [extrait et comparatif du POC](/01-cadrage-saclay/02-scenarios/03-extrait-et-comparatif-du-poc).

Noms du modèle du graphe (IKG), sauf préfixe `CSV` ou `Prisma` (base de SoVisu+). Sens métier : [modèle de données](./modele-de-donnees) ; stockages : [stockages et schémas](./stockages-et-schemas) ; règles de choix : [provenance, qualité et fusion](./provenance-qualite-fusion).

## Formats et conventions

| Champ ou format | Règle observée | Statut |
|---|---|---|
| `uid` | Clé métier commune aux composants ; distincte de l'entier local `Prisma.id` | **Confirmé** |
| Identifiant `{type, value}` | Référence dans un système externe ou local ; le type fait partie de la clé | **Confirmé** |
| `Literal {value, language}` | Libellé multilingue ; langue absente notée `ul` ; valeur tronquée à 4 000 caractères | **Confirmé** |
| Date partielle de publication | Garde la précision disponible (`2024`, `2024-03`, `2024-03-12`) ; ne pas inventer de jour | **Confirmé** |

### Conservation des textes entre IKG et PostgreSQL

Statut : **Confirmé** par exécution locale le 22 octobre 2026 ([procédure](/03-crisalid/04-tutoriels/02-preuves/verifier-contrat-textes)).

| Texte | Limite du graphe | Limite de SoVisu+ | Conséquence |
|---|---|---|---|
| Titre de publication | 4 000 | 2 000 | Un titre accepté par le graphe peut être refusé par SoVisu+ |
| Libellé de structure | 4 000 | 255 | Pas de réduction automatique |
| Description de structure | 4 000 | 2 000 | Même écart |
| Résumé | 4 000 | illimité | Troncature dans le graphe |

Une erreur de longueur laisse un état partiel (titre écrit, résumé ancien) : **une projection en erreur n'est pas un instantané exportable**.

### Rejeu et réconciliation des textes

Rejouer une entrée invalide reproduit l'erreur sans doublon ; rejouer un instantané corrigé rétablit les textes. Mais **un ancien instantané réinjecté après un plus récent est accepté** et efface les textes récents : aucun garde-fou de révision. Statut : **Confirmé** ; rejeu via les files d'erreur **À confirmer**.

## Personnes et identifiants

| Champ | Définition | Persistance | Statut |
|---|---|---|---|
| `uid` | Fourni, ou calculé depuis un identifiant prioritaire | Graphe → SoVisu+ | **Confirmé** |
| `names`, `display_name` | Prénoms et noms ; nom affiché calculé à défaut | Graphe → Apollo → SoVisu+ | **Confirmé** |
| `identifiers` | `local`, `eppn`, `orcid`, `idref`, `idhals`, `idhali`, `scopus` | Graphe | **Confirmé** |
| `validated`, `authenticated` | Qualification d'un identifiant ; un `false` ne révoque pas un ancien `true` | Graphe ; non exposés par Apollo | **Partiel** |
| `external` | Personne hors annuaire, créée par rapprochement bibliographique (coauteur externe) | Graphe → Apollo → SoVisu+ | **Confirmé** |
| `Prisma.Person.email` | Email de la personne | **SoVisu+ seulement** : renseigné à la connexion ou à la création du compte, pas par le graphe | **Confirmé** |

### Entrées CSV sans continuité démontrée

Statut : **Confirmé** par exécution ([procédure](/03-crisalid/04-tutoriels/02-preuves/verifier-contrat-bridge-ikg)). Les emails de contact et d'authentification, le type d'appartenance et la HDR sont émis par la passerelle d'annuaire puis **ignorés** par le graphe. Un identifiant `researcherid` fait **rejeter** la personne : le type n'existe pas dans le graphe.

### Sélection réelle des colonnes par le lecteur CSV

Statut : **Confirmé** par exécution ([procédure](/03-crisalid/04-tutoriels/02-preuves/preparer-directory-bridge)). Le lecteur CSV de la passerelle ne lit que les colonnes attendues : emails, HDR, type d'appartenance, dates d'appartenance et `researcherid` sont écartés **avant** conversion ; une colonne requise absente fait échouer la lecture. Pour les structures, une ligne sans identifiant local est ignorée ; deux lignes de même clé donnent la dernière.

## Appartenances et emplois

| Champ | Définition | Persistance | Statut |
|---|---|---|---|
| `memberships[].entity_uid` | Structure de rattachement | `MEMBER_OF`, si la structure existe | **Confirmé** |
| `employments[].entity_uid` | Établissement employeur (UAI ou ROR) | `EMPLOYED_AT` | **Confirmé** |
| `position_code` | Code de corps ou de poste (donnée RH) | Propriété de `EMPLOYED_AT` | **Confirmé** |
| `start_date`, `end_date` | Dates acceptées par le modèle d'entrée | **Non écrites** dans le graphe, bien que déclarées par Apollo et SoVisu+ | **Confirmé** |

Conséquence : pas d'historique des affiliations ([modèle de données](./modele-de-donnees#rattachements-de-personnes-sans-dates)).

## Structures et relations organisationnelles

| Champ | Définition | Exposition | Statut |
|---|---|---|---|
| `uid`, `identifiers` | Identifiants local, UAI, ROR, IdRef, RNSR | Apollo → SoVisu+ | **Confirmé** |
| `generic_type`, `national_type` | Famille et type national | Apollo → SoVisu+ | **Confirmé** |
| `short_labels`, `long_labels`, `descriptions` | Libellés multilingues | Apollo → SoVisu+ | **Confirmé** |
| `addresses`, `electronical_addresses` | Adresses et sites | Non déclarés dans Apollo | **Partiel** |
| `parents`, `memberships` | Inclusions et rattachements entre structures, avec dates | Apollo → SoVisu+ | **Confirmé** |
| `Prisma.hidden` | Masquage propre à SoVisu+ | SoVisu+ seulement | **Confirmé** |

## Notices sources et documents

| Champ | Définition | Exposition | Statut |
|---|---|---|---|
| `SourceRecord.uid`, `harvester`, `source_identifier`, `url` | Notice d'une source donnée | Apollo → SoVisu+ | **Confirmé** |
| Identifiants de notice | DOI, HAL, OpenAlex… ; type inconnu noté `unknown` | Graphe | **Confirmé** |
| `harvested_for` | Personne pour qui la collecte a été lancée, pas forcément auteur | Graphe | **Confirmé** |
| `Document.uid` | Identifiant, remplacé par celui du document conservé après fusion | Apollo → SoVisu+ | **Confirmé** |
| `titles`, `abstracts`, `subjects` | Résultat de la stratégie puis des corrections | Apollo → SoVisu+ | **Confirmé** |
| `publication_date`, `document_type` | Date partielle ; type élu | Apollo → SoVisu+ | **Confirmé** |
| `contributions` | Auteurs reliés aux personnes consolidées | Apollo → SoVisu+ | **Confirmé** |
| `publication_channels` | Revue, volume, numéro, pages | Graphe ; une seule revue côté SoVisu+ | **Partiel** |
| `topics` | Thèmes OpenAlex ou Taxi | Absent du type publication d'Apollo | **Partiel** |
| `open_access_status` | Statut d'accès ouvert | Partiellement dans Apollo | **Partiel** |

### Dépôt HAL et fichiers associés (SoVisuPlus)

Les états de dépôt HAL et les fichiers déposés sont conservés **uniquement dans la base et sur le disque de SoVisu+**, pas dans le graphe : ils ne se reconstruisent pas depuis Neo4j. Statut : **Confirmé**.

## Provenance, fraîcheur et corrections

- Les horodatages disponibles datent **la collecte** ou **la mise à jour de la copie dans SoVisu+**, jamais la modification dans la source : aucun ne garantit un délai source → vitrine.
- Chaque correction porte un identifiant (`application:id`), sa cible, son auteur déclaré, le champ, l'action (ajout, retrait, modification, fusion) et son résultat (appliquée ou en échec). Ces champs ne disent rien de l'autorisation.
- Une date de fraîcheur complète et la source gagnante **par champ** restent **À confirmer** ([provenance](./provenance-qualite-fusion)).

## Preuves techniques

- Graphe `ebdaae75` : [modèles](https://github.com/CRISalid-esr/crisalid-ikg/tree/ebdaae75/app/models), [requêtes](https://github.com/CRISalid-esr/crisalid-ikg/tree/ebdaae75/app/graph/neo4j/queries), [validateurs de textes](https://github.com/CRISalid-esr/crisalid-ikg/blob/ebdaae75/app/models/text_literal.py).
- Passerelle d'annuaire `95be05d7` : [sélection des colonnes](https://github.com/CRISalid-esr/crisalid-directory-bridge/blob/95be05d7/tasks/fetch_from_spreadsheet.py), [convertisseur personnes](https://github.com/CRISalid-esr/crisalid-directory-bridge/blob/95be05d7/tasks/spreadsheet/convert_spreadsheet_people.py).
- Apollo `d377579a` : [schéma GraphQL](https://github.com/CRISalid-esr/crisalid-apollo/blob/d377579a/src/schema.ts).
- SoVisu+ `8e571657` : [schéma Prisma](https://github.com/CRISalid-esr/SoVisuPlus/blob/8e571657/prisma/schema.prisma), [accès aux personnes](https://github.com/CRISalid-esr/SoVisuPlus/blob/8e571657/src/app/lib/daos/PersonDAO.ts).
- Moissonneur `6898db85` : [modèle de collecte](https://github.com/CRISalid-esr/svp-harvester/blob/6898db85/app/db/models/harvesting.py).

Les révisions sont centralisées dans [Sources et preuves](/03-crisalid/00-reperes/sources-et-preuves).