Changelog SGRDV — release 1.0.3

Date de publication : 7 mai 2026

Légende : 🔴 = rupture sur contrat de production (experimental = false) · 🟠 = rupture sur contrat en validation (experimental = true) · 🟢 = ajout rétrocompatible

1. Versionnement et statut

1.1 Bump 1.0.2 → 1.0.3 🟢

Cette release applique un bump PATCH cumulant cinq blocs de correctifs : un défaut de conception sur le profil partagé SGRDVBaseRequestProvenance (voir §2), un nettoyage des bindings ValueSet sur les profils communs de $find (voir §4), l'ajout du lien Location.managingOrganization dans la réponse $find (voir §5), une réduction des matérialisations dans les bundles de réponse $find / $lock / $extend-lock (voir §6), et un relâchement de cardinalité de l'OperationOutcome à 0..* dans les réponses qui le transportent (voir §7). Aucun nouvel artefact n'est introduit ; aucun statut d'artefact ne change. Tous les artefacts versionnés (config IG, OperationDefinition, CapabilityStatement) sont alignés sur la version 1.0.3. L'attribut experimental = true est conservé sur tous les artefacts.

Le bump est conforme à la politique de versionnement publiée en 1.0.2 : ruptures sur des artefacts experimental = true → bump PATCH.

2. Provenance.agent — who et onBehalfOf en logical references contraintes 🟠

S'applique aux deux surfaces (api-sgrdv et api-source) et à toutes les opérations ($find, $aggregate, $lock, $extend-lock, $release-lock), via le profil parent commun SGRDVBaseRequestProvenance.

2.1 Contexte du correctif

Depuis 1.0.0, SGRDVBaseRequestProvenance.agent.who était typé Reference(SGRDVBaseSourceSystemDevice) et les exemples utilisaient une référence littérale (reference = "Device/sgrdv-example-device-..."). De même, agent.onBehalfOf portait une référence littérale (reference = "Organization/...").

Défaut identifié : ni le Device cible de agent.who, ni l'Organization cible de agent.onBehalfOf n'étaient embarqués dans le payload Parameters de la requête. Ces deux références littérales étaient donc pendantes : le récepteur (SGRDV core ou DMÉ/SIP-C) n'avait aucun moyen de résoudre l'identité du système source ni l'organisation pour le compte de laquelle la demande était émise.

Le correctif aligne ces deux références sur le pattern logical reference (identifier-only) déjà retenu en 1.0.2 pour practitioner / clinic / gmf / slot.

2.2 agent.who — logical reference vers un NamingSystem de système source 🟠

NamingSystems reconnus pour agent.who.identifier.system :

Note sur identifier.value : un système source qui s'identifie comme « Votre santé » ou « OMNIMED » n'a généralement pas d'identifiant interne stable à fournir — la value est laissée optionnelle et n'est peuplée que pour les déploiements multi-instances ou multi-tenants. La best-practice constraint FHIR ident-1 (« Identifier with no value has limited utility ») peut émettre un warning de validation lorsque value est absent ; ce warning est attendu et accepté pour ce profil — l'identification du système source est portée par identifier.system seul.

2.3 agent.onBehalfOf — logical reference vers une Organization (CodeEtablissement RAMQ) 🟠

Le pattern est aligné sur le filtre clinic du $find (déjà appliqué en 1.0.2). L'identifier.value est ici obligatoire car elle porte le code d'établissement RAMQ — c'est une vraie identification d'une clinique, pas d'un système logiciel.

3. Nettoyage technique 🟢

3.1 Retrait des exemples Device

Les exemples de ressources Device représentant les portails et le SGRDV core (introduits en 1.0.0 à titre illustratif) sont retirés du IG. Ils n'étaient plus référencés par aucune Provenance après le passage en logical reference, et leur conservation aurait introduit du bruit dans le rendu sans valeur ajoutée.

Aucune action partenaire requise — ces exemples n'ont jamais voyagé en runtime.

3.2 Profil SGRDVBaseSourceSystemDevice conservé

Le profil SGRDVBaseSourceSystemDevice (parent : Device) reste défini. Il n'est jamais matérialisé dans le payload de requête, mais il sert :

1. de typage cible de la Reference dans SGRDVBaseRequestProvenance.agent.who — l'intention sémantique « système source » reste documentée au niveau du type ;
2. de parent du futur profil SGRDVAuditAgent (cf. ADR-016 — Bundle d'audit auto-portant), qui sera lui matérialisé dans SGRDVAuditBundle.entry avec deviceName.name rempli. Les contraintes deviceName 1..1 et deviceName.type = #manufacturer-name du parent restent utiles pour cet usage.

4. Nettoyage des bindings ValueSet sur les profils communs $find 🟠

S'applique aux profils communs partagés par les deux surfaces (api-sgrdv et api-source) pour l'opération $find. Aucun nouveau ValueSet n'est introduit — les VS référencés (SGRDVAppointmentTypeVS, SGRDVTimeslotCategoryVS, SGRDVTrajectoireVS, SGRDVVolunteerPractitionerVS, SGRDVSpecialtyVS, SGRDVOrganizationTypeVS, SGRDVSiteTypeVS) existent depuis 1.0.0.

4.1 Ajout de bindings manquants sur SGRDVBaseFindResponseAppointment 🟠

Trois éléments du profil portaient MS sur leur Coding sans liaison à un ValueSet — défaut découvert lors d'une revue Simplifier. Le contrat est désormais explicite.

Les exemples d'instance étaient déjà conformes à ces VS et systèmes — aucun ajustement de payload requis pour les implémentations qui suivaient déjà les exemples publiés.

4.2 Slicing de SGRDVBaseFindResponsePractitionerRole.code pour volunteerPractitioner 🟠

L'élément PractitionerRole.code ne portait jusqu'à 1.0.2 aucune liaison ValueSet. Il est désormais slicé pour expliciter le code « médecin volontaire / non-volontaire » (entente MSSS-FMOQ).

Le slicing #open permet l'ajout futur d'autres rôles (référent, garde, etc.) sans rupture rétrocompatible avec ce slice.

4.3 Bindings remontés au niveau CodeableConcept (override propre du binding FHIR base) 🟠

Huit bindings auparavant attachés au sous-élément .coding ont été remontés au niveau du CodeableConcept parent. Cela override proprement le binding de base FHIR R4 (qui s'exprime au niveau CC) — Simplifier affichait jusque-là le binding de base (ex. PracticeSettingCodeValueSet pour specialty) au lieu du binding SGRDV.

Impact sémantique :

• Avant : chaque Coding répété devait être dans le VS — interdisait toute traduction depuis un autre système (ex. libellé local).
• Après : la CodeableConcept doit contenir au moins un Coding du VS — d'autres traductions sont permises si pertinentes.

Pour les profils où coding.system reste fixé (exactly) (ex. $sct pour specialty, $v3-role-code pour Location.type), la sémantique reste de facto identique au binding .coding précédent ; pour Organization.type (système libre), la nouvelle binding est strictement plus permissive.

5. Ajout du lien Location.managingOrganization dans la réponse $find 🟠

S'applique au profil commun SGRDVBaseFindResponseLocation (et par héritage aux deux surfaces api-sgrdv et api-source). Aucun nouveau profil n'est introduit — SGRDVBaseFindOrganization existe depuis 1.0.0 et est désormais réutilisé comme cible de Location.managingOrganization.

5.1 Contexte du correctif

Jusqu'à 1.0.2, la réponse $find matérialisait le Location du rendez-vous via Appointment.participant[location], mais aucune référence n'était posée vers l'organisation gestionnaire de ce lieu (clinique propriétaire). Le portail consommateur n'avait donc pas de moyen FHIR-natif d'afficher le nom de la clinique associée à une disponibilité — il devait inférer l'organisation depuis le contexte de la requête (filtre clinic / gmf), ce qui ne couvrait pas les recherches géographiques (location-string + rayon).

Le correctif s'appuie sur l'élément Location.managingOrganization natif de FHIR R4.

5.2 SGRDVBaseFindResponseLocation.managingOrganization 🟠

La référence est littérale (résolue dans le Bundle de réponse, pas en logical reference) : l'Organization cible est matérialisée dans le Bundle via la nouvelle entry organization (cf. §5.3). Ce choix diffère du pattern logical reference appliqué aux requêtes ($find filtres, Provenance.agent) : ici on est en réponse searchset, le récepteur doit pouvoir afficher le nom et le code RAMQ de la clinique sans aller-retour additionnel.

5.3 SGRDVBaseFindResponseBundle.entry[organization] 🟢

La cardinalité 0..* reste cohérente avec celles de entry[location], entry[appointment], etc. — un Bundle vide (0 résultat) reste valide. En revanche, dès qu'un Location est matérialisé, son managingOrganization étant désormais 1..1, l'Organization cible doit être présente dans le Bundle.

6. Réduction des matérialisations dans les bundles de réponse 🟠

S'applique aux bundles de réponse $find (deux surfaces) et $lock / $extend-lock (surface api-sgrdv). Trois ressources matérialisées sans valeur métier nette ont été réduites ou retirées.

6.1 $find réponse — Slot en logical reference 🟠

Le profil SGRDVBaseDmeSlot reste défini : il sert de typage cible de la Reference dans Appointment.slot (intention sémantique « plage horaire DMÉ ») et reste la cible matérialisée dans SGRDVBaseLockCandidateAppointment.slot côté payload $lock.

Justification : seul Slot.identifier est consommé par le portail (pour les opérations subséquentes $lock / $extend-lock). Slot.start/end étaient redondants avec ceux de l'Appointment, Slot.schedule.reference n'était pas exploitable hors contexte DMÉ, et Slot.status était transitoire (la Appointment.status prend le relais).

6.2 $find réponse — Patient retiré complètement 🟠

Le profil SGRDVBaseFindPatient reste défini : il continue de typer parameter[patient].resource dans le payload de requête $find / $aggregate.

Justification : le DMÉ n'enrichit pas le Patient transmis en entrée. Le portail connaît déjà le patient pour lequel il a interrogé SGRDV et la corrélation requête/réponse passe par le HTTP X-Correlation-Id — aucun besoin de retransmettre l'identité du patient dans la réponse.

6.3 $lock réponse — lockedAppointment en logical reference 🟠

S'applique au profil SGRDVLockResultParameters et au bundle SGRDVLockResponseBundle.

Le profil SGRDVLockResponseAppointment reste défini : il sert de typage cible de la Reference dans parameter[lockedAppointment].

Justification : $lock accepte une liste de disponibilités candidates en entrée — la réponse doit donc identifier laquelle a été verrouillée. Une logical reference (identifier seul) suffit pour ce besoin ; la ressource Appointment matérialisée ne portait que identifier (= entrée), status et participant.actor (référence Organization littérale) — aucune information nouvelle.

6.4 $extend-lock — entrée resserrée à 1..1, pas de lockedAppointment en réponse 🟠

S'applique aux profils SGRDVExtendLockRequestParameters (api-sgrdv) et SGRDVSourceExtendLockNotificationParameters (api-source).

Contrairement à $lock qui accepte plusieurs candidates et doit donc désigner laquelle a été verrouillée, $extend-lock cible un verrou unique identifié par son lockIdentifier. Le profil SGRDVLockResultParameters est partagé : parameter[lockedAppointment] reste défini (0..1) mais n'est pas peuplé pour $extend-lock.

6.5 Impact côté payload

• $find réponse : suppression de 1 à N entries Slot, suppression d'1 entry Patient, suppression de la branche participant[patient] dans chaque Appointment retourné. La taille du Bundle baisse proportionnellement au nombre de disponibilités.
• $lock réponse : suppression de l'entry lockedAppointment (1 ressource par succès). La référence à la disponibilité verrouillée bascule en logical reference dans SGRDVLockResultParameters.
• $extend-lock réponse : suppression de l'entry lockedAppointment ; aucun parameter[lockedAppointment] ajouté (le lockIdentifier suffit).

7. OperationOutcome retourné en cardinalité 0..* dans les réponses 🟢

S'applique aux trois réponses d'opération qui transportent un corps : $find (deux surfaces), $aggregate (deux surfaces) et $lock / $extend-lock (surface api-sgrdv). Aucun nouveau profil n'est introduit — le profil SGRDVBaseOperationOutcome reste inchangé.

7.1 Justification

Une opération SGRDV peut produire plusieurs OperationOutcome indépendants en réponse — par exemple un warning MaxCountExceeded par DMÉ ayant atteint la limite _count côté $find, ou un mélange d'issues informatives et d'avertissements distincts. La cardinalité 0..1 posée jusqu'en 1.0.2 forçait à fusionner ces messages dans une seule ressource OperationOutcome (au prix de la perte d'identité de chaque émetteur), alors que la cardinalité naturelle est 0..*.

Les opérations dont la réponse est exclusivement HTTP 204 (Source $lock / $extend-lock / $release-lock) ne sont pas concernées — elles n'ont pas de corps. L'opération $release-lock côté api-sgrdv retourne 204 en succès et un OperationOutcome nu (hors Bundle) en erreur — la pluralité y est déjà portée par SGRDVBaseOperationOutcome.issue 1..*.

7.2 Cardinalités modifiées

Les profils dérivés (SGRDVFindResponseBundle, SGRDVSourceFindResponseBundle, SGRDVAggregateResponseParameters, SGRDVSourceAggregateResponseParameters) héritent du relâchement sans modification additionnelle.

7.3 Impact partenaire

Aucun. Le changement est strictement rétrocompatible : les payloads existants qui contenaient 0 ou 1 OperationOutcome restent valides. Les implémentations capables d'agréger plusieurs OperationOutcome distincts dans la réponse peuvent désormais le faire sans contrainte de cardinalité.

8. Recommandations de migration pour les partenaires

Si vous émettez une Provenance dans $find, $aggregate, $lock, $extend-lock ou $release-lock

1. agent.who — remplacer toute reference = "Device/..." par une logical reference :

   • agent.who.identifier.system = URL du NamingSystem de votre système source (cf. tableau §2.2). Exemple pour le portail Votre santé : http://sante.quebec/fhir/NamingSystem/VOTRESANTE.
   • agent.who.identifier.value — optionnelle. Ne la peupler que si votre déploiement comporte plusieurs instances ou tenants à distinguer ; sinon, l'omettre est valide et préférable.

2. agent.onBehalfOf (si vous l'utilisez — l'élément reste optionnel) — remplacer toute reference = "Organization/..." par une logical reference :

   • agent.onBehalfOf.identifier.system = http://sante.quebec/fhir/NamingSystem/RAMQ (ou autre NamingSystem applicable)
   • agent.onBehalfOf.identifier.value = code d'établissement RAMQ
   • agent.onBehalfOf.identifier.type.coding.system = http://sante.quebec/fhir/CodeSystem/sgrdv-identifier-type et .code = #CodeEtablissement

Si vous produisez ou consommez des réponses $find

Les bindings ValueSet ajoutés en §4 sont alignés sur les CodeSystem SGRDV existants depuis 1.0.0. Vérifier que :

• Appointment.appointmentType.coding.system = http://sante.quebec/fhir/CodeSystem/sgrdv-appointment-type (codes URGENT, SEMIURGENT, SUIVI, SGROSSESSE, SPEDIATRIQUE, PRISECHARGE).
• Appointment.serviceCategory.coding.system = http://sante.quebec/fhir/CodeSystem/sgrdv-timeslot-category (codes p4p5, GAP, POP).
• Appointment.serviceType.coding.system = http://sante.quebec/fhir/CodeSystem/sgrdv-trajectoire (codes SAG-GI, PGM, RTA) — uniquement si serviceType est peuplé.
• Pour PractitionerRole.code, utiliser le slice volunteerPractitioner (code.coding.system = http://sante.quebec/fhir/CodeSystem/sgrdv-volunteer-practitioner, codes VOLONTAIRE / NVOLONTAIRE).

Les implémentations qui suivaient déjà les exemples publiés en 1.0.2 n'ont aucun ajustement à faire.

Si vous (DMÉ/SIP-C) émettez des réponses $find, ou si vous (portail) les consommez

1. Côté DMÉ/SIP-C (émetteur) — pour chaque Location retourné dans le Bundle de réponse, peupler Location.managingOrganization.reference vers une instance Organization (profil SGRDVBaseFindOrganization) ajoutée comme entry du Bundle. L'Organization doit porter au minimum :
   • identifier.system = http://sante.quebec/fhir/NamingSystem/RAMQ (ou autre NamingSystem applicable)
   • identifier.value = code d'établissement RAMQ
   • identifier.type.coding.system = http://sante.quebec/fhir/CodeSystem/sgrdv-identifier-type et .code = #CodeEtablissement
   • name = libellé d'affichage de la clinique
2. Côté portail (consommateur) — résoudre Location.managingOrganization.reference dans le Bundle pour afficher le nom et le code de la clinique associée à chaque disponibilité. Ne pas inférer l'organisation depuis le filtre clinic / gmf de la requête : ce filtre est optionnel et ne couvre pas les recherches géographiques.

Si vous validez vos instances avec un validateur FHIR

Le warning ident-1 (« Identifier with no value has limited utility ») peut apparaître sur agent.who.identifier lorsque value est absent. C'est attendu et conforme à ce profil — pas une non-conformité.

Toutes intégrations confondues

1. Mettre à jour les références internes (validation, documentation, dépendances de paquet) à la version 1.0.3 des artefacts. Aucun changement de statut (#active / #draft) ni de l'attribut experimental = true par rapport à 1.0.2.
2. Conserver la politique de versionnement et de stabilité publiée en 1.0.2 : tant qu'un artefact est experimental = true, ses ruptures n'entraînent qu'un bump PATCH du paquet — c'est ce qui s'applique à cette release.