docs: update documentation for implementing capability statement (#7)

* Rename files

* add version control parameters to sushi config

* refine technical documentation on version management

* update instance names to include version numbers

* expand capability statement examples to include multiple roles

* refine technical documentation on capability statement versioning

* Adjust text

* reading cs

* input hugo

Author: gbeskers

input/fsh/ANWBronhouderCapabilityStatement-v1.fsh renamed to input/fsh/ANWBronhouderCapabilityStatement-v1.0.0.fsh

@@ -1,4 +1,4 @@
-Instance: ANWBronhouderCapabilityStatement-v1
+Instance: ANWBronhouderCapabilityStatement-v1.0.0
 InstanceOf: CapabilityStatement
 Usage: #definition
 Title: "ANW Bronhouder Capability Statement v1.0.0"

input/fsh/ANWRegisseurCapabilityStatement-v1.fsh renamed to input/fsh/ANWRegisseurCapabilityStatement-v1.0.0.fsh

@@ -1,4 +1,4 @@
-Instance: ANWRegisseurCapabilityStatement-v1
+Instance: ANWRegisseurCapabilityStatement-v1.0.0
 InstanceOf: CapabilityStatement
 Usage: #definition
 Title: "ANW Regisseur Capability Statement v1.0.0"

input/fsh/ANWSearchOperationDefinition-v1.fsh renamed to input/fsh/ANWSearchOperationDefinition-v1.0.0.fsh

@@ -1,4 +1,4 @@
-Instance: ANW-zorg
+Instance: ANW-zorg-v1.0.0
 InstanceOf: OperationDefinition
 Usage: #definition
 * id = "ANW-zorg"

input/fsh/ANWZorgverlenerCapabilityStatement-v1.fsh renamed to input/fsh/ANWZorgverlenerCapabilityStatement-v1.0.0.fsh

@@ -1,4 +1,4 @@
-Instance: ANWZorgverlenerCapabilityStatement-v1
+Instance: ANWZorgverlenerCapabilityStatement-v1.0.0
 InstanceOf: CapabilityStatement
 Usage: #definition
 Title: "ANW Zorgverlener Capability Statement v1.0.0"

input/pagecontent/technical-documentation-v1.md

@@ -729,31 +729,46 @@ ze beschikbaar moeten stellen.
 | notification | Endpoint waar de notificatie naar toe gestuurd kan worden om mee te delen dat er een authorisatie door een “ANW-Bronhouder” is aangemaakt |
 
 # Versie beheer
-Voor versie beheer van de usecase wordt er gebruikt gemaakt van capability statements in FHIR. Een capability statement beschrijft alle functionaliteit die een FHIR server beschikbaar heeft. Het capability statement van FHIR fhir server is aan te roepen op het {baseUrl}/metadata endpoint. Dit endpoint moet publiekelijk, zonder authenticatie, aan te roepen zijn.
+Voor versie beheer van de usecase wordt er gebruikt gemaakt van capability statements in FHIR. Een capability statement beschrijft alle functionaliteit die een FHIR server beschikbaar heeft. Het capability statement van de FHIR server is aan te roepen op het {baseUrl}/metadata endpoint. Dit endpoint moet publiekelijk, zonder authenticatie aan te roepen zijn.
 
 *Hoe geef je als server aan welke versie van een rol ondersteund?*
 
-Per unieke rol kan je aangeven welke versie(s) je ondersteund van de specifieke rol. Het capability statement heeft een *instantiates* veld waarin meerdere url's kunnen worden vastgelegd. M.b.v. instantiates kan je verwijzen naar een capability statement die je FHIR server implementeerd. In deze documentatie hebben we de capability statements vastgelegd van de versies van de verschillende rollen die er zijn, deze zijn terug te vinden onder de [artifacts](artifacts.html). In het capability statement ziet dit er dan als voorbeeld als volgt uit:
+Per unieke rol kan je aangeven welke versie je ondersteund van de specifieke rol. Het capability statement heeft een *instantiates* veld waarin meerdere url's kunnen worden vastgelegd. M.b.v. instantiates kan je verwijzen naar een capability statement die je FHIR server implementeerd. In deze documentatie hebben we de capability statements vastgelegd van de versies van de verschillende rollen die er zijn, deze zijn terug te vinden onder de [artifacts](artifacts.html). In het capability statement ziet dit er dan als voorbeeld als volgt uit wanneer een FHIR server ondersteuning biedt voor de ANW Bronhouder en ANW Zorgverlener rol:
 ```json
 {
   "resourceType": "CapabilityStatement",
   "instantiates": [
-    "https://nuts-foundation.github.io/nl-anw-ig/CapabilityStatement-ANWBronhouderCapabilityStatement-v1.json"
+    "https://nuts-foundation.github.io/nl-anw-ig/CapabilityStatement-ANWBronhouderCapabilityStatement-v1.0.0.json",
+    "https://nuts-foundation.github.io/nl-anw-ig/CapabilityStatement-ANWZorgverlenerCapabilityStatement-v1.0.0.json"
   ]
 }
 ```
 In het voorbeeld hierboven wordt er gebruik gemaakt van de versie van de ANW-Bronhouder rol die beschreven staat in het capability statement van wanneer je de link zou openen, in dit geval versie 1.0.0. Als software leverancier weet je op basis van welke URL's een andere partij in het instantiates heeft staan, welke versie van een rol die allemaal ondersteund.
 
 ## Huidige versies
-
 |Rol | Versie | Url | artificat |
 |----|--------|-----|-----------|
-|ANW-Bronhouder| 1.0.0 | https://nuts-foundation.github.io/nl-anw-ig/CapabilityStatement-ANWBronhouderCapabilityStatement-v1.json | [link](CapabilityStatement-ANWBronhouderCapabilityStatement-v1.html) |
-|ANW-Zorgverlener|1.0.0 |https://nuts-foundation.github.io/nl-anw-ig/CapabilityStatement-ANWZorgverlenerCapabilityStatement-v1.json | [link](CapabilityStatement-ANWZorgverlenerCapabilityStatement-v1.html) |
-|ANW-Regisseur|1.0.0|https://nuts-foundation.github.io/nl-anw-ig/CapabilityStatement-ANWRegisseurCapabilityStatement-v1.json| [link](CapabilityStatement-ANWRegisseurCapabilityStatement-v1.html) |
+|ANW-Bronhouder| 1.0.0 | https://nuts-foundation.github.io/nl-anw-ig/CapabilityStatement-ANWBronhouderCapabilityStatement-v1.0.0.json                                                         | [link](CapabilityStatement-ANWBronhouderCapabilityStatement-v1.0.0.html) |
+|ANW-Zorgverlener|1.0.0 | https://nuts-foundation.github.io/nl-anw-ig/CapabilityStatement-ANWZorgverlenerCapabilityStatement-v1.0.0.json                                                       | [link](CapabilityStatement-ANWZorgverlenerCapabilityStatement-v1.0.0.html) |
+|ANW-Regisseur|1.0.0| https://nuts-foundation.github.io/nl-anw-ig/CapabilityStatement-ANWRegisseurCapabilityStatement-v1.0.0.json | [link](CapabilityStatement-ANWRegisseurCapabilityStatement-v1.0.0.html) |
 
 ## Implementeren van een nieuwe versie
-Op het moment wanneer er een nieuwe functionaliteit voor een rol uitgedacht wordt, dan resulteert dit in een nieuwe versie van het capability statement. In de documentatie zal dan een nieuw hoofdstuk komen van de functionaliteit die nieuw is en welke nieuwe versies van het capability statement daarbij horen. Wanneer een leverancier de nieuwe functionaliteit ontwikkeld heeft dan kan deze de bijbehorende link naar het nieuwe capability statement toevoegen bij de instantiates, welke aangeeft dat de nieuwe functionaliteit beschikbaar is en de aanroepende kanten van het metadata hier op kunnen sturen. **Let op**: Het is hier wel belangrijk dat voorgaande links naar versies van een dezelfde rol nog wel in het capability statement van het metadata endpoint blijven staan. Zo geef je aan dat je ook nog de voorgaande versie ondersteund en backwards compatible bent. Als voorbeeld er komt een versie 2.x.x beschikbaar en de vorige versie is 1.x.x, dan op het moment dat je de functionaliteit van 2.x.x aanzet in je capability statement vervang je niet de link naar 1.x.x, deze blijft ook in het capability statement staan. Dit blijft tot dat iedereen gebruik maakt van een rol, over is op de nieuwere versies en kunnen oudere versies uitgefaseerd worden.
+Op het moment wanneer er een nieuwe functionaliteit voor een rol uitgedacht wordt, dan resulteert dit in een nieuwe versie van het capability statement. In de documentatie zal dan een nieuw hoofdstuk komen van de functionaliteit die nieuw is en welke nieuwe versies van het capability statement daarbij horen. 
+
+Wanneer een leverancier de nieuwe functionaliteit ontwikkeld heeft, dan kan deze de bijbehorende link naar het nieuwe capability statement toevoegen bij de instantiates, welke aangeeft dat de nieuwe functionaliteit beschikbaar is en de aanroepende kanten van het metadata hier op kunnen sturen.
+
+**Let op**: We hebben afgesproken dat we altijd per rol slechts één versie aanbieden. Dus als er een nieuwe versie 2.x.x beschikbaar is die de leverancier ondersteunt, hoeft de leverancier alleen deze aan te passen in het meta endpoint.
+
+Wanneer een nieuwe versie wordt geïmplementeerd, moet deze altijd backwards compatible zijn met de voorgaande versies. Dit betekent dat bestaande functionaliteit en koppelingen met eerdere versies blijven werken, zodat afnemers niet direct hoeven over te stappen.
+
+## Versie controleren
+Een aanvrager kan de versie van een rol controleren door binnen de instantie lijst in het meta endpoint alle IG met 
+betrekking tot ANW uit te lezen en hier de versie te resolven. De versie kan geresolved worden door het versie veld 
+binnen het capability statement uit te lezen. Als aanvrager kijk je dan dus of de versie gelijk of hoger is dan de 
+versie waarvan je als aanvrager de functionaliteit ondersteund. Bijvoorbeeld als je als aanvrager versie 1.2.0 hebt 
+en er komt versie 1.3.0 terug, dan doe je de vergelijking 1.3.0 > 1.2.0, wat betekent dat je als aanvrager alle 
+functionaliteit die je hebt kan gebruiken. Is de versie van de aanvrager hoger is dan de versie van de leverancier, 
+dan moeten er functionaliteiten verbogen worden.
 
 # Uitbreidingen (gemaakt zonder versiebeheer)
 

sushi-config.yaml

@@ -18,6 +18,10 @@ publisher:
   name: Stichting Nuts
   url: https://www.nuts.nl
 
+parameters:
+  apply-version: false  # Prevent overwriting resource-specific versions
+  default-version: true # Use IG version as fallback for resources without explicit version
+
 menu:
   Home: index.html
   Documentation: