VER - Eisen (en aanbevelingen) voor versiebeheer

001. Er zijn momenteel geen algemene standaarden die definiëren hoe het beheer van versies moet worden geïmplementeerd.

002. Een duidelijk versiebeleid is cruciaal voor Koppeltaal.

003. Aanpassingen en/of wijzigingen op configuratie items (CI) kunnen door belanghebbende worden ingediend bij Koppeltaal.

004. Aanpassingen en/of wijzigingen op configuratie items (zoals interfaces, resources of functies) worden verdeeld in een Minor- of Major wijziging. (zie Semantic Versioning 2.0.0)

005. Een Major wijziging verstoort het proces of functionaliteit waarbij cliënten functionele en technische aanpassingen MOETEN uitvoeren om de nieuwe wijziging te ondersteunen.

006. Een Minor wijziging verstoort NIET het huidige proces of functionaliteit.

007. Omdat interacties de basis vormen voor alle functionaliteit van Koppeltaal, mogen ze niet onaangekondigd wijzigen binnen één versie van Koppeltaal.

008. Fouten mogen in deze schema's wel conform een fout-procedure worden verbeterd. Hiervoor zullen tussentijdse "builds" opgeleverd worden, indien nodig op de laatste en voorlaatste Koppeltaal versie.

009. Tussentijdse "builds" kunnen ook worden gebruikt om kleinere, functionele wijzigingen te realiseren, in dat geval echter uitsluitend op de meest recente Koppeltaal-versie. Een tussentijdse "build" bevat alleen kleinere aanpassingen die geen gevolgen zullen hebben voor bestaande Koppeltaal-implementaties op basis van de laatste en/of de voorlaatste (Major) Koppeltaal-release.

010. Een Koppeltaal versie nummering is opgebouwd uit <Major nummer>.<Minor nummer>.<Build nummer>, zodat naar elke unieke configuratie item verwezen kan worden

011. Koppeltaal interface specificaties (koppelvlakken) worden vastgelegd met de OpenAPI Specification (OAS)

012. Koppeltaal profielen zijn gebaseerd op v4.0.1: R4

013. Koppeltaal profielen worden geregistreerd bij Simplifier.net/Koppeltaalv2.0

014. Koppeltaal Canonical Base URL is http://koppeltaal.nl/

015. Het project FHIR API endpoint van Koppeltaal is beschikbaar bij: https://fhir.simplifier.net/Koppeltaalv2.0

016. Koppeltaal publiceert zowel Major versies/releases als eventuele tussentijds builds van de betreffende Koppeltaal-voorzieningen en toepassingen, inclusief specificaties/documentatie, op de website van Koppeltaal

017. Leveranciers en gebruikers wordt geadviseerd de meeste recente (Major) versie zo spoedig mogelijk in software te implementeren respectievelijk deze voor te schrijven.

018. Gebruikers of leveranciers die extra elementen, buiten de standaard, aan Koppeltaal willen toevoegen kunnen hiertoe wijzigingsverzoek indienen bij Koppeltaal. .

Aanbevelingen

a001. Voor het beschrijven en specificeren van de Koppeltaal interfaces wordt geadviseerd om gebruik te maken van de OpenAPI Specification 3.0. Hierin worden interfaces eenduidig en leesbaar vastgelegd, zonder te hoeven weten hoe deze geïmplementeerd is. Zie Home - OpenAPI Initiative (openapis.org).

a002. Voeg Major wijzingen toe in de URI van een API (basis pad) met prefix 'v'. Minor- en Build nummers NIET toevoegen in de URI.

a003. Voeg de volledige Koppeltaal versie nummering toe in de response header. Voorbeeld: "API-Version: 1.0.2"

a004. Publiceer een wijzigingslog tussen twee versies.