Add versioning by M-Priour · Pull Request #733 · ansforge/IG-terminologie-de-sante

M-Priour · 2026-01-26T17:12:48Z

Hello,
J'ai ajouté une page pour expliquer le versioning des ValueSet :

https://ansforge.github.io/IG-terminologie-de-sante/ig/add-versioning/versioning.html#gestion-des-versions-des-valuesets

Est-ce que cela vous semble clair ?

Cdlt

dcohenAns · 2026-01-26T17:26:00Z

C'est super clair.
Puisqu'on en parle, j'ai plein de questions :
Les 2 JDV auront- ils le même oid?
Quid des versions des TRE ?
Serait-il possible de dire que l'ID = libellé ID +[version] soit ID&1.0.0 par exemple ?
Quid des formats historiques des NOS ( nom des fichiers ) : Est-ce envisageable de créer un répertoire pour l'ensemble des NOS d'une version anterieure à la version en cours (active ou non) avec les mêmes noms de fichiers ?

Merci++
Danielle

nriss · 2026-01-27T06:21:57Z

Ces 2 JDV auront- ils le même oid?

Les 2 JDVs seront exactement les mêmes mis à part l'id logique (= id technique) et les modifications apportées entre les deux versions. Si l'oid n'a pas été changé entre les deux versions, ils auront donc le même oid.

Quid des versions des TRE ?

Ca fonctionne pareil

Serait-il possible de dire que l'ID = libellé ID +[version] soit ID&1.0.0 par exemple ?

Je n'ai pas très bien compris. C'est à dire donner une convention de nommage pour les id techniques ?
Selon FHIR, l'id doit respecter cette regex : [A-Za-z0-9-.]{1,64} donc le & ne serait pas autorisé.
Je pense que le mieux c'est effectivement de garder l'id tel qu'il est actuellement, et de le suffixer par la version s'il s'agit d'une version historique. Qu'en pensez-vous ?

Quid des formats historiques des NOS ( nom des fichiers ) : Est-ce envisageable de créer un répertoire pour l'ensemble des NOS d'une version anterieure à la version en cours (active ou non) avec les mêmes noms de fichiers ?

Je n'ai pas très bien compris, dans l'API il n'y a pas de nom de fichiers à priori

dcohenAns · 2026-01-27T09:45:33Z

Merci @nriss pour tes retours.
Pour la règle de nommage de l'ID, je n'ai pas de préférence particuière si ce n'est de permettre d'ajouter le contenu du champ "version"

Pour les fichiers historiques, je voulais parler des noms des ressources NOS des versions anterieures ( qui ne sont ni le name, ni l'ID Fhir)

ex des noms des répertoires de chaque ressources TRE NOS :

ex des fichiers (non fhir) :

dcohenAns · 2026-01-27T09:51:15Z

@nriss ,
il me semble qu'un nouveau répertoire NOS par version, ex "NOS 2025.12 " éviterait de changer les noms des ressources.
Merci de votre aide

input/pagecontent/versioning.md

sga-esante · 2026-01-27T10:01:16Z

input/pagecontent/versioning.md

+
+##### Approche retenue
+
+Créer des ressources avec la **même URL** et des **identifiants (`id`) différents** pour chaque version.


Pourquoi est-il nécessaire de créer des identifiants différents vu que la structure JSON d'un valueSet permet de gérer avec un même id plusieurs versions (l'attribut "versionId" utilisé probablement par l'historique permet de les distinguer) ?

Est-il possible d'avoir accès aux issues ou autres sources techniques du projet utilisé par le SMT pour comprendre cette contrainte de devoir recréer une nouvelle ressource à chaque mise à jour?

Je ne suis pas sûr de comprendre.
Dans un serveur FHIR, le logical id permet d'identifier ne manière unique une ressource.
On ne peut en avoir deux ressources accessible en même temps avec le même identifiant logique

Le versionning est une forme d'historique permettant d'accéder à une version antérieur de la version courante.
Pour l'historique, il n'est pas nécessaire d'avoir un logical id par historique, or tu peux bien accéder au contenu des différents historiques.
De la même façon, il n'est pas nécessaire d'avoir un logical id par version et pouvoir accéder aux versions antérieures.

J'ajoute un exemple concret pour lequel tu as le même logical id et bien 2 versions distinctes.
Je laisse volontairement dans l'extrait le champ versionId qui est également important:

https://smt.esante.gouv.fr/fhir/CodeSystem/TRE-R244-CategorieOrganisation/_history/9

{ "resourceType": "CodeSystem", "id": "TRE-R244-CategorieOrganisation", "meta": { "versionId": "9", ... } "version": "20241025120000", "name": "TRE_R244_CategorieOrganisation",

https://smt.esante.gouv.fr/fhir/CodeSystem/TRE-R244-CategorieOrganisation

{ "resourceType": "CodeSystem", "id": "TRE-R244-CategorieOrganisation", "meta": { "versionId": "26", ... }, "version": "20251222120000", "name": "TRE_R244_CategorieOrganisation",

Oui, accessible via history, mais un seul dans la version courante.
C'est ce qui est expliqué dans la documentation.

Le serveur de terminologie (FTS) gère automatiquement l’historique des versions :

Historique accessible : Le FTS conserve l’historique de toutes les versions via _history

@sga-esante : est-ce que c'est plus clair ?
Sinon, je propose de faire un point

Oui, il faut faire un point (et me donner en amont les éléments pour que je puisse y réfléchir avant):
Je pense qu'il ne faut pas coupler la gestion des versions du SMT avec le sujet particulier FINESS+.
Il me parait dangereux d'avoir plusieurs versions actives d'un valueSet ou d'un codeSystem car je pense que les versions des codeSystems ne sont pas faite pour cela (on tord ce concept de versionning des codeSystem).
Je pense que les codeSystem et valueSet ne sont pas fait pour avoir plusieurs versions actives simultanément.
Comme le sujet semble complètement couplé avec FINESS+, est ce que je peux avoir la liste des TRE/JDV consommés par le ROR et concernés par ce sujet pour que j'y réfléchisse avant ce point?
Ainsi que le scénario que vous souhaitez proposer au projet ROR ? Ex: comment souhaitez-vous modifier l'IG du ROR vers ces TRE? En ajoutant la version dans les urls des JDV/TRE mentionnées dans l'IG du ROR?

Vu avec Mael;
La version peut être utilisée dans plusieurs contextes, , en fonction du contexte la def d'une version peut changer, incrémenation systématique à chaque mise à jour (ex TRE du NOS), ou une version par pays (ex un logical-id snomed international, un logical id snomed fr pour un même codesystem) ou autre.
Plusieurs historiques peuvent (meta.versionId) peuvent partager une même version.

Oui comme indiqué, c'est un cas exceptionnel :

input/pagecontent/versioning.md

dcohenAns · 2026-01-27T10:15:03Z

Sylvain, @sga-esante
Je pose un point avec toi ASAP pour te parler de la nécessité d'avoir 2 versions actives d'une même ressource terminologique dans les NOS.

sga-esante · 2026-01-27T16:57:25Z

input/pagecontent/versioning.md

+Dans FHIR, chaque ValueSet possède deux attributs clés pour le versioning :
+- **`url`** : identifiant canonique unique et stable (ne change jamais)
+- **`version`** : numéro de version de la ressource
+
+```json
+{
+  "resourceType": "ValueSet",
+  "url": "http://exemple.fr/fhir/ValueSet/mon-jeu-de-valeurs",
+  "id" : "mon-jeu-de-valeur",
+  "version": "1.0.0",
+  "name": "MonJeuDeValeurs",
+  "status": "active"
+}


Description du champ versionId et ajout dans l'exemple
Modification la valeur du champ version car dans le cas général, la version est une date.

Suggested change

Dans FHIR, chaque ValueSet possède deux attributs clés pour le versioning :

- **`url`** : identifiant canonique unique et stable (ne change jamais)

- **`version`** : numéro de version de la ressource

```json

{

"resourceType": "ValueSet",

"url": "http://exemple.fr/fhir/ValueSet/mon-jeu-de-valeurs",

"id" : "mon-jeu-de-valeur",

"version": "1.0.0",

"name": "MonJeuDeValeurs",

"status": "active"

}

Dans FHIR, chaque ValueSet possède deux attributs clés pour le versioning :

- **`url`** : identifiant canonique unique et stable (ne change jamais)

- **`version`** : numéro de version de la ressource

Un 3e attribut meta.versionId est auto-incrémenté à chaque mise à jour du ValueSet. Il est utilisé pour conserver l'historique de chaque modification.

```json

{

"resourceType": "ValueSet",

"url": "http://exemple.fr/fhir/ValueSet/mon-jeu-de-valeurs",

"id" : "mon-jeu-de-valeur",

"meta": {

"versionId": "9",

...

}

"version": "20240927120000",

"name": "MonJeuDeValeurs",

"status": "active"

}

sga-esante · 2026-01-27T17:08:59Z

input/pagecontent/versioning.md

+
+- **Historique accessible** : Le FTS conserve l'historique de toutes les versions via `_history`
+- **Dernière version par défaut** : Sans précision, c'est toujours la version la plus récente qui est retournée
+- **Cas standard** : Une seule version active à la fois, les anciennes sont archivées dans l'historique


Suggested change

- **Cas standard** : Une seule version active à la fois, les anciennes sont archivées dans l'historique

Le serveur de terminologie (FTS) conserve automatiquement l'historique de chaque changement du ValueSet.

Dans le cas standard, chaque changement du ValueSet correspond à une nouvelle version du ValueSet.

C'est à dire qu'à chaque incrément de "_meta.versionId_" correspond une nouvelle "_version_".

La "_version_" renseignée est de type "date" (https://www.hl7.org/fhir/codesystem-version-algorithm.html)

Mais dans certains cas, une même "_version_" pourra être commune à plusieurs changements du ValueSet, c'est à dire à plusieurs "_meta.versionId_". Ces cas sont décrit dans le paragraphe suivante "_Cas exceptionnels : plusieurs versions actives_".

- **Historique accessible** : Le FTS conserve l'historique de toutes les versions via `_history`

- **Dernière version par défaut** : Sans précision, c'est toujours la version la plus récente qui est retournée

- **Cas standard** : Une seule version active à la fois, les anciennes sont archivées dans l'historique

#### Exemples d'appels API

**Récupérer la version active :**

GET [base]/ValueSet?url=http://exemple.fr/fhir/ValueSet/statut-patient

sga-esante · 2026-01-27T17:20:02Z

input/pagecontent/versioning.md

+| Version | URL (canonique) | id (technique) |
+|---------|-----------------|----------------|
+| 1.0.0 | `http://exemple.fr/fhir/ValueSet/statut-patient` | `statut-patient-v1` |
+| 2.0.0 | `http://exemple.fr/fhir/ValueSet/statut-patient` | `statut-patient-v2` |
+


Suggested change

| Version | URL (canonique) | id (technique) |

|---------|-----------------|----------------|

| 1.0.0 | `http://exemple.fr/fhir/ValueSet/statut-patient` | `statut-patient-v1` |

| 2.0.0 | `http://exemple.fr/fhir/ValueSet/statut-patient` | `statut-patient-v2` |

| Version | URL (canonique) | id (technique) |

|---------|-----------------|----------------|

| 1.0.0 | `http://exemple.fr/fhir/ValueSet/statut-patient` | `statut-patient-v1` |

| 2.0.0 | `http://exemple.fr/fhir/ValueSet/statut-patient` | `statut-patient-v2` |

Ainsi il sera possible de faire évoluer la version 1.0.0 en parallèle de la version 2.0.0.

Lorsque la version 1.0.0 sera mise à jour, l'attribut "_version_" conservera la valeur "1.0.0", seul l'attribut "_meta.versionId_" s'incrémentera (contrairement au cas nominal ou l'attribut "_version_" change à chaque incrément de "_meta.versionId_".

Ex:

Après avoir été mis à jour, le meta.versionId de mon ValueSet "mon-jeu-de-valeur" passe à la valeur 2, la version, par contre, reste à "1.0.0"

```json

{

"resourceType": "ValueSet",

"url": "http://exemple.fr/fhir/ValueSet/mon-jeu-de-valeurs",

"meta": {

"versionId": "2",

...

}

}

"version": "1.0.0",

"name": "MonJeuDeValeurs",

"status": "active"

}

sga-esante · 2026-01-27T17:22:45Z

input/pagecontent/versioning.md

+
+**Récupérer la dernière version :**
+```
+GET [base]/ValueSet?url=http://exemple.fr/fhir/ValueSet/statut-patient


Cette requête est-elle encore possible lorsqu'on active les versions?

Comment le SMT peut-il déduire quelle est la dernière version?
La 1.0.0 ou la 2.0.0?

S'il se base sur la dernière mise à jour, il peut alors considérer que la dernière version est la 1.0.0 si celle-ci a été mise à jour plus récemment que la 2.0.0...

Cette requête est-elle encore possible lorsqu'on active les versions?

Le SMT renverra deux ValueSet s'il y en a deux avec la même URL

Comment le SMT peut-il déduire quelle est la dernière version?

FHIR R5 a introduit un champs versionAlgorithm pour déterminer quelle est la plus récente
https://www.hl7.org/fhir/valueset.html

D'accord, j'ai mis à jour mes propositions dans la PR pour décrire ce point.

Il faut tester que cela fonctionne bien sur le SMT actuel car ca semble assez avancé.

Suggested change

GET [base]/ValueSet?url=http://exemple.fr/fhir/ValueSet/statut-patient

Le serveur de terminologie retournera la version la plus haute (cf https://www.hl7.org/fhir/valueset-version-algorithm.html)

GET [base]/ValueSet?url=http://exemple.fr/fhir/ValueSet/statut-patient

Etant donné que c'est des attributs ajoutés en R5 et que le SMT est en R4, il faudra rajouter ces informations à l'aide d'extension standard si on va dans cette direction

Est-ce que ca signifie que ca ne fonctionne pas sur le SMT tel qu'il est aujourd'hui en production?
Et que des devs supplémentaires sur le SMT seront nécessaires pour que cela fonctionne?

Ca mérite d'être testé en pprod, je ne sais pas si ça fonctionnerait, si on peut utiliser des extensions, ...

dcohenAns · 2026-01-28T07:32:31Z

Bonjour à tous @sga-esante , @nriss , @M-Priour
Au cas où, je viens de faire 2 petits schemas sur le cas de la TRE R66 que l'on souhaiterait avec 2 versions actives en même temps (cas exceptionnel pour une dizaine de TRE en 2026) :

Situation actuelle ( "Plan B" qui porte à confusion mais simple )
2 TRE distinctes pour un même contenu, avec 2 OID

Situation souhaitée : En utilisant la gestion des versions
1 TRE avec 2 versions actives

Qu'en pensez vous ?

Merci de votre attention
A plus
Danielle

dcohenAns · 2026-01-28T19:26:26Z

Re-bonjour,
J'ai une nouvelle question :
Les champs suivants d'une ressource CodeSystem sont-ils les seuls champs qui ne peuvent PAS changer entre 2 versions ?

resourceType ex : "CodeSystem"
url ex : https://mos.esante.gouv.fr/NOS/TRE_R257-TypeBAL/FHIR/TRE-R257-TypeBAL
identifier ( OID) ex : urn:oid:1.2.250.1.213.3.3.55
name ex: TRE_R257_TypeBAL

Si c'est le cas, nous sommes bien obligés de créer des "doublons" pour la refonte des TRE Finess qui sont renommées
(Et mon exemple du message précedant reste valable pour les NOS mais il ne pourra pas s'appliquer pour la TRE R66...)

Merci +++
Danielle

sga-esante · 2026-01-29T09:04:45Z

input/pagecontent/versioning.md

+Créer des ressources avec la **même URL** et des **identifiants (`logical id`) différents** pour chaque version.
+


Suggested change

Créer des ressources avec la **même URL** et des **identifiants (`logical id`) différents** pour chaque version.

Créer des ressources avec la **même URL** et des **identifiants (`logical id`) différents** pour chaque version.

La "_version_" renseignée est alors de type "semver" (https://www.hl7.org/fhir/codesystem-version-algorithm.html)

M-Priour added 4 commits January 26, 2026 15:14

Create versioning.md

d02e1a4

Update versioning.md

17de78f

Fix titles and add versioning resource in config

bc3833c

Update versioning.md

d39c907

M-Priour requested review from nriss and sga-esante January 26, 2026 17:15

nriss approved these changes Jan 27, 2026

View reviewed changes

sga-esante reviewed Jan 27, 2026

View reviewed changes

input/pagecontent/versioning.md Show resolved Hide resolved

sga-esante reviewed Jan 27, 2026

View reviewed changes

input/pagecontent/versioning.md Outdated Show resolved Hide resolved

Update versioning documentation for logical id

c348d60

sga-esante self-requested a review January 27, 2026 16:31

sga-esante reviewed Jan 27, 2026

View reviewed changes

sga-esante reviewed Jan 29, 2026

View reviewed changes


		##### Approche retenue

		Créer des ressources avec la même URL et des identifiants (`id`) différents pour chaque version.

-- **Cas standard** : Une seule version active à la fois, les anciennes sont archivées dans l'historique
+Le serveur de terminologie (FTS) conserve automatiquement l'historique de chaque changement du ValueSet.
+Dans le cas standard, chaque changement du ValueSet correspond à une nouvelle version du ValueSet.
+C'est à dire qu'à chaque incrément de "_meta.versionId_" correspond une nouvelle "_version_".
+La "_version_" renseignée est de type "date" (https://www.hl7.org/fhir/codesystem-version-algorithm.html)
+Mais dans certains cas, une même "_version_" pourra être commune à plusieurs changements du ValueSet, c'est à dire à plusieurs "_meta.versionId_". Ces cas sont décrit dans le paragraphe suivante "_Cas exceptionnels : plusieurs versions actives_".
+- **Historique accessible** : Le FTS conserve l'historique de toutes les versions via `_history`
+- **Dernière version par défaut** : Sans précision, c'est toujours la version la plus récente qui est retournée
+- **Cas standard** : Une seule version active à la fois, les anciennes sont archivées dans l'historique
+#### Exemples d'appels API
+**Récupérer la  version active :**
+GET [base]/ValueSet?url=http://exemple.fr/fhir/ValueSet/statut-patient

	GET [base]/ValueSet?url=http://exemple.fr/fhir/ValueSet/statut-patient
	Le serveur de terminologie retournera la version la plus haute (cf https://www.hl7.org/fhir/valueset-version-algorithm.html)
	GET [base]/ValueSet?url=http://exemple.fr/fhir/ValueSet/statut-patient

Conversation

M-Priour commented Jan 26, 2026

Uh oh!

dcohenAns commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nriss commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dcohenAns commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dcohenAns commented Jan 27, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

M-Priour Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sga-esante Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dcohenAns commented Jan 27, 2026

Uh oh!

sga-esante Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sga-esante Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sga-esante Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sga-esante Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dcohenAns commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dcohenAns commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

dcohenAns commented Jan 26, 2026 •

edited

Loading

nriss commented Jan 27, 2026 •

edited

Loading

dcohenAns commented Jan 27, 2026 •

edited

Loading

M-Priour Jan 27, 2026 •

edited

Loading

sga-esante Jan 27, 2026 •

edited

Loading

sga-esante Jan 27, 2026 •

edited

Loading

sga-esante Jan 27, 2026 •

edited

Loading

sga-esante Jan 29, 2026 •

edited

Loading

sga-esante Jan 29, 2026 •

edited

Loading

dcohenAns commented Jan 28, 2026 •

edited

Loading

dcohenAns commented Jan 28, 2026 •

edited

Loading