Standaarden en richtlijnen epv. Versienummering. Datum 19 december Onderwerp Standaarden en richtlijnen Versienummering

Standaarden en richtlijnen ePV Versienummering

Datum 19 december 2006 Onderwerp Standaarden en richtlijnen Versienummering Auteur Marc de Graauw Hugo den Hollander E-mail [email protected] Versie 1.0 - Definitief Opdrachtgever Programma ePV

1

Inleiding

1.1

Inleiding

Elektronische berichtenuitwisseling tussen organisaties in de strafrechtsketen vraagt van de deelnemende organisaties een vergaande standaardisering van begrippen en definities. Goed beheer van opgeleverde producten vereist strakke toepassing van de regels inzake versiebeheer en versienummering. Dit document beschrijft een algemene versiebeheerstrategie voor binnen ePV te beheren objecten. Toepassing van de regels voor major en minor versienummers cf. UBL NDR 1.0.1 zou betekenen dat elke kleine wijziging in een definitie moet leiden tot uitbrengen van een nieuwe release voor grote groepen gebruikers. Dit is een onevenredig zware belasting voor gebruikers. Om dit te voorkomen wordt (aansluitend bij UBL NDR 2.0) in de naamgeving van schema’s, bestanden etc. in een release alleen het major versienummer opgenomen.

1.2

Referenties

[1] Universal Business Language (UBL) Naming and Design Rules 1.0.1, OASIS, november 2004 [2] Universal Business Language (UBL) Naming and Design Rules 2.0, OASIS, May 2006 (DRAFT, dit is geen normatieve uitgave).

2

Te beheren objecten

De te beheren objecten zijn de componenten van het ePV vocabulaire: − Gegevenselement (ABIE, BBIE en ASBIE) − Code-element − Groep (bedrijfsdocument, woordenboek, codelijst) − Datatype Voor toelichting over de betekenis van deze componenten zie de overige ePV documentatie. Dit wordt hier verder alleen besproken voor zover dit de issues in dit document direct raakt. ePV volgt voor het maken van deze documenten de UBL Naming and Design Rules 1.0.1 [1] – verder NDR1. Van deze regel wordt afgeweken voor gebruik van namespaces voor versies. Hiervoor worden UBL Naming and Design Rules v. 2.0 [2] – verder NDR2 gevolgd. Van belang is allereerst de opdeling in XML Schema-bestanden. ePV gebruikt aparte bestanden voor: − het ePV gegevenswoordenboek met alle gegevensdefinities en herbruikbare groepen; − voor ieder bedrijfsdocument, zoals InvorderingRijbewijs; − voor alle codetabellen; − schema's van UBL met bijvoorbeeld datatypen. Dit leidt conform de NDR1 tot aparte namespaces, bijvoorbeeld: "urn:epv:names:specification:bedrijfsdocument:schema:xsd:PvInvorderingRijbewijs-1.0" voor een bedrijfsdocument en "urn:epv:names:specification:bedrijfsdocument:schema:xsd:Gegevenswoordenboek-1.0" voor het gegevenswoordenboek.

Datum:

19 december 2006

Document:

Standaarden en Richtlijnen voor Versienummering ePV

Pagina 2 van 9

Versie:

1.0

Beheerder: ePV Project: Programma ePV

Het gegevenswoordenboek wordt geïmporteerd in de XML Schema's voor de bedrijfsdocumenten. Een voorbeeld, op plaatsen ingekort met ... voor de leesbaarheid: <xsd:schema version="1.0" targetNamespace="urn:epv:names:...:PvInvorderingRijbewijs-1.0" ... xmlns="urn:epv:names:...:PvInvorderingRijbewijs-1.0" xmlns:gwb="urn:epv:names:...:Gegevenswoordenboek-1.0" > <xsd:import namespace="urn:epv:names:...:Gegevenswoordenboek-1.0" schemaLocation="../common/EPV-Gegevenswoordenboek-1.0.xsd" />

Een codelijst bestaat uit een tabel en een waardebereik (opsomming van alle mogelijke waarden). Definitie en waardebereik worden vastgelegd in een XML Schema. Elke codelijst heeft zijn eigen XML Schema bestand. Een schema voor een bedrijfsdocument kan verwijzen naar een schema van een codelijst. Deze verwijzing gaat via een namespace declaratie en een importstatement.

3

Upgrade problematiek

Bij versiebeheer in gegevensuitwisseling is de problematiek wat complexer dan in ‘gewone’ automatisering. Traditioneel betekent backward compatibiliteit dat een softwareprogramma versie 2 gegevens kan lezen die geschreven zijn met softwareprogramma versie 1. Forward compatibiliteit is het omgekeerde. In gewone softwareontwikkeling is backward compatibiliteit veel belangrijker dan forward compatibiliteit. Vertaald naar XML Schema's betekent dit dat er backward compatibiliteit is wanneer ieder XML bestand dat valide is voor XML Schema versie 1, dit ook is voor XML Schema versie 2. Oftewel: de verzameling XML instances die valide is volgens XML Schema versie 1 is een deelverzameling van de verzameling XML instances die valide is volgens XML Schema versie 2. Een voorbeeld: een landcode die in versie 1 waarden {NL, BE} mag hebben en in versie 2 waarden {NL, BE, DE} is backward compatibel. Voor de situatie bij ePV betekent dit het volgende. Een bedrijfsdocument B doet een import van het gegevenswoordenboek G en een codetabelschema C. Wanneer de namespace van G of C wijzigt, moet het import-statement in B wijzigen, en krijgt dus ook B zelf een nieuwe versie. Dit is niet altijd wenselijk. Als er een gegevenswoordenboek versie 1 is met gegevenselementen: G1 = {a, b, c} En er zijn twee bedrijfsdocumenten die G importeren en de volgende gegevenselementen gebruiken: B1 = {a, b} C1 = {a, c} Wanneer nu het woordenboek en de bedrijfsdocumenten wijzigen omdat er een nieuw bedrijfsdocument gedefinieerd wordt: G = {a, b, c, d} B = {a, b} C = {a, c}

Datum:

19 december 2006

Document:


Pagina 3 van 9

Versie:

1.0


D = {a, d) De documenten B en C zijn feitelijk niet gewijzigd. Nu is het de vraag wat er gebeurt met de namespaces. Als dit leidt tot nieuwe namespaces: G2 = {a, b, c, d} B2 = {a, b} C2 = {a, c} D1 = {a, d) betekent dit dat B en C een nieuwe versie moeten krijgen omdat G een nieuwe versie heeft en G geïmporteerd wordt. Dit is niet wenselijk, omdat afnemers die alleen documenten B en C gebruiken nieuwe versies moeten gaan gebruiken terwijl er in hun situatie niets wijzigt. Er zijn een paar strategieën om dit te vermijden: 1. Dubbele ontvangers. Ontvangers die D willen gebruiken moeten naast de nieuwe versie ook de oude versie bewaren. Ze moeten dus zowel B1 als B2 kunnen verwerken. Dan kunnen zenders nog steeds B1 sturen. 2. Delta's gebruiken. In G2 zitten alleen de wijzigingen, en G2 importeert G1. G1 = {a, b, c} G2 = {import van G1, d} B1 = {a, b} C1 = {a, c} D1 = {a, d) 3. Namespace handhaven. Uitbreidingen in G1 toestaan zonder dat de namespace wijzigt. G1 = {a, b, c, d} B1 = {a, b} C1 = {a, c} D1 = {a, d) Optie 1 legt uiteraard een last op ontvangers. Optie 2 met delta's en imports is complex in het beheer, daar is dus niet voor gekozen. Optie 3 is de gekozen optie. Nadeel is dat niet aan de namespace van het woordenboek te zien is welke versie het is, maar dat is op te lossen met een goede distributie.

4

Versiebeheer in Unicorn

Unicorn volgt de hierboven beschreven regels voor versienummering. Een project kent verschillende versies van bedrijfsdocumenten (Unicorn-‘data assets’), groepen en woordenboeken. In Unicorn wordt geen versiebeheer gepleegd op het niveau van Unicorn-‘concepts’, dat wil zeggen individuele gegevenselementen. De versies van de bedrijfsdocumenten en woordenboeken kennen een onderlinge afhankelijkheid. Unicorn kent 1 versienummer <major.minor> voor een compleet project. Voorbeeld: Project 1.0 bevat BD-A 1.0 en GWB 1.0

Datum:

19 december 2006

Document:


Pagina 4 van 9

Versie:

1.0


Project 1.1 bevat BD-A 1.1 en GWB 1.0 Project 1.2 bevat BD-A 1.1 en GWB 1.1 Project 1.3 bevat BD-A 1.1 en GWB 1.2 Project 1.4 bevat BD-A 1.1 en GWB 1.3 Project 1.5 bevat BD-A 1.1 en GWB 1.4 Project 1.6 bevat BD-A 1.2 en GWB 1.4 Bij de export van schema’s wordt een Namespace gekozen. In de namespace wordt alleen het major versienummer opgenomen. Het major versienummer wordt zowel voor project, bedrijfsdocument als woordenboek gebruikt. Consequentie van deze werkwijze is dat kunnen gaten in de versienummering van bedrijfsdocumenten kunnen ontstaan.

5

Versiebeheersystematiek

Hier worden de gekozen oplossingen voor versiebeheer in ePV besproken. De keuzes hebben als uitgangspunt het beheer eenvoudig te houden, en de ketenpartners zo weinig mogelijk lastig te vallen met nieuwe versies.

5.1

Een major wijziging leidt tot een nieuwe namespace

5.2

Een minor wijziging leidt niet tot een nieuwe namespace

We sluiten wat dit betreft aan bij NDR2, tenminste de koers die de meest recente Draft suggereert.

5.3

Minor versies moeten volledig backward compatibel zijn.

Dus voor een minor versie n.y geldt: alle XML bestanden die valide zijn onder n.x waar x < y, moeten ook valide zijn onder n.y.

5.4

Minor versies worden bijgehouden buiten de namespace om.

Versie wordt bijgehouden in bijvoorbeeld in namen van bestanden en begeleidende documentatie. Te overwegen valt de informatie in een XML Schema in een annotation element bij te houden en in een XML instance in een comment element.

5.5

Toevoegingen aan het gegevenswoordenboek leiden tot een minor versie

Met deze keuze kunnen nieuwe gegevenselementen en bedrijfsdocumenten toegevoegd worden zonder dat afnemers van bestaande documenten naar nieuwe versies hoeven te upgraden. Er komt geen nieuwe namespace van het gegevenswoordenboek, dus alle bestaande bedrijfsdocumenten kunnen ongewijzigd blijven.

5.6

Wijzigingen in bestaande elementen in het gegevenswoordenboek leiden tot een major versie

Er is niet voor gekozen om bijvoorbeeld het toevoegen van optionele elementen in een groep in een minor versie te doen. In kaart brengen van alle wijzigingen dit backward compatibel zijn, is in principe mogelijk, maar er is voor gekozen op dit moment te kiezen

Datum:

19 december 2006

Document:


Pagina 5 van 9

Versie:

1.0


voor eenvoud in de regels voor versienummering. Mocht er behoefte ontstaan om backward-compatibele wijzigingen in een minor release onder te brengen, dan kunnen deze regels aangepast en uitgebreid worden.

5.7

Ieder gegevenswoordenboek is compleet met alle gegevenselementen

Geen import en delta's voor het gegevenswoordenboek. We volgen richtlijn NMS6 (UBL published namespaces MUST never be changed) uit NDR1 niet voor ePV.

5.8

Geen minor versie voor bedrijfsdocumenten

Bedrijfsdocumenten kennen bij voorkeur alleen major versies, met nieuwe namespaces. Het is in principe wel mogelijk optionele toevoegingen binnen een minor versie, en dus dezelfde namespace te doen, maar wijzigingen zullen normaal gesproken toch leiden tot wijzigingen in het proces bij de uitwisselende partijen. Een nieuwe major versie is dan op zijn plaats. Dit is typisch een deelgebied waar praktijkervaring nodig is. In internationale ontwikkelingen wordt ook geworsteld met deze zaken, dus geen verbod op minor versies van bedrijfsdocumenten. De praktijk kan uitwijzen dat het soms toch wenselijk is. Als er toch een minor versie van een bedrijfsdocument komt gelden de volgende restricties: − Er is sprake van backward compatibiliteit als hierboven in richtlijn 3 beschreven. − Het is niet wenselijk of mogelijk dat alle zenders upgraden (anders is het ook niet nodig). − Alle ontvangers zullen wel upgraden (anders krijgen ze binnen een namespace documenten die ze mogelijk niet kunnen lezen). − Met distributiebeheer wordt gewaarborgd dat alle ketenpartners de voor hen juiste versies van XML Schema's en documentatie hebben.

5.9

Gewijzigde bedrijfsdocumenten leiden tot softwareupgrades en/of dubbele ontvangers

Wanneer het schema van een bedrijfsdocumenttype wijzigt kunnen er twee strategieën gevolgd worden: 1. alle ketenpartners gaan upgraden naar de nieuwe versie; 2. alle ontvangers gaan de oude en de nieuwe versie ondersteunen, en zenders gaan over op de nieuwe versie wanneer ze die echt gebruiken. De eerste strategie is raadzaam wanneer veel zenders de nieuwe versie kunnen produceren, de tweede wanneer slechts enkele ketenpartners baat hebben bij de nieuwe versie. (Noot: bij optie 2 is gebruik maken van een minor versie van een bedrijfsdocument een optie.) bedrijfsdocument een optie.)

6

Codetabellen

In grote lijnen geldt voor Codetabellen hetzelfde als voor bedrijfsdocumenten.

7

UBL NDR Naming and Design Rules

Binnen ePV worden de UBL NDR 1.0 Naming en Design Rules (verder: NDR1) gebruikt. De belangrijkste punten uit de NDR1 zijn:

Datum:

19 december 2006

Document:


Pagina 6 van 9

Versie:

1.0


−

− − −

Ieder XML Schema bestand krijgt een eigen namespace, dus bij ePV bestanden voor het gegevenswoordenboek, ieder bedrijfsdocument en iedere codetabel een eigen namespace; Er worden major en minor versies onderscheiden; De schema's van een minor versie 1.1 moeten alle XML bestanden die gemaakt zijn met versie 1.0 valideren (backward compatible); De namespaces eindigen in versienummers voor major en minor versie, dus naam<major>.<minor>. Deze regel wordt bij ePV niet gevolgd.

Zie de bijlage voor een overzicht van de Rules die relevant zijn voor ePV versiebeheer: Uitgangspunt is dat voor iedere wijziging er een nieuwe versie komt, en dat er dus ook een nieuwe namespace komt. Verder gaat de NDR1 ervan uit dat een geïmporteerde namespace nooit wijzigt. Wanneer er een minor versie n.1 komt, zitten alleen de wijzigingen daar in. In n.1 wordt het schema van n.0 geïmporteerd. In n.0 wordt dus niets gewijzigd. Schema's die verwijzen naar n.0 hoeven dus ook niet gewijzigd te worden, alleen wanneer ze de gewijzigde zaken uit n.1 willen gebruiken, moeten ze gaan verwijzen naar n.1, en dus zelf ook een nieuwe versie krijgen. Er wordt op dit moment gewerkt aan UBL NDR versie 2. Het belangrijkste verschil voor versiebeheer is dat de minor versie niet langer in de namespace opgenomen wordt. Een overzicht van de wijzigingen in NDR2 staat in de bijlage.

Datum:

19 december 2006

Document:


Pagina 7 van 9

Versie:

1.0


Bijlage: UBL Naming en Design Rules ePV volgt zoveel mogelijk de UBL NDR1, en voor versienummering NDR2. De NDR1 zijn specifiek voor UBL geschreven, en uiteraard wijkt ePV op dit punt af. Lees dus "ePV" waar "UBL" staat, bijvoorbeeld "ePV schema" of "ePV code list". Waar OASIS staat kan ook ePV gelezen worden, bijvoorbeeld "urn:epv:names ..." etc. Alleen regels die relevant zijn voor versionering en die toegepast worden in ePV zijn opgenomen.

7.1

UBL Naming en Design Rules v. 1.0.1

A.3 Code List Rules CDL1 All UBL Codes MUST be part of a UBL or externally maintained Code List. CDL5 The name of each UBL Code List Schema Module MUST be of the form: {Owning Organization}{Code List Name}{Code List Schema Module} CDL6 An xsd:import element MUST be declared for every code list required in a UBL schema. A.15 Namespace Rules NMS1 Every UBL-defined or -used schema module MUST have a namespace declared using the xsd:targetNamespace attribute. NMS5 The namespace names for UBL Schemas holding OASIS Standard status MUST be of the form: urn:oasis:names:specification:ubl:schema:<subtype>:<documentid> NMS17 Each UBL:CodeList schema module MUST be maintained in a separate namespace. A.21 Versioning Rules VER4 Every minor version release of a UBL schema or schema module OASIS Standard MUST have an RFC 3121 document-id of the form -<major >.<non-zero> VER5 For UBL Minor version changes, the name of the version construct MUST NOT change. VER6 Every UBL Schema and schema module major version number MUST be a sequentially assigned, incremental number greater than zero. VER8 A UBL minor version document schema MUST import its immediately preceding version document schema. VER10 UBL Schema and schema module minor version changes MUST not break semantic compatibility with prior versions.

7.2

UBL Naming en Design Rules v. 2.0 (DRAFT)

NMS2 VER1 VER2 VER3 VER5

Every UBL-defined-or -used major version schema set MUST have its own unique namespace. Every UBL Schema and schema module major version committee draft MUST have an RFC 3121 document-id of the form -<major>[.] Every UBL Schema and schema module major version OASIS Standard MUST have an RFC 3121 document-id of the form -<major> Every minor version release of a UBL schema or schema module draft MUST have an RFC 3121 document-id of the form -<major>[.] For UBL Minor version changes the namespace name MUST not change

Datum:

19 december 2006

Document:


Pagina 8 van 9

Versie:

1.0


VER11

VER12

VER13

VER14

VER15

Every UBL Schema and schema module major version committee draft MUST capture its version number in the xsd:version attribute of the xsd:schema element in the form <major>.0[.] Every UBL Schema and schema module major version OASIS Standard MUST capture its version number in the xsd:version attribute of the xsd:schema element in the form <major>.0 Every minor version release of a UBL schema or schema module draft MUST capture its version information in the xsd:version attribute in the form <major>.<non-zero>[.] Every minor version release of a UBL schema or schema module OASIS Standard MUST capture its version information in the xsd:version attribute in the form <major>.<non-zero> Every UBL document schema MUST include a required element named "UBLVersion" as the first child of its root element. This element MUST have a default value that matches the value of the xsd:version attribute of its containing schema.

Datum:

19 december 2006

Document:


Pagina 9 van 9

Versie:

1.0


Standaarden en richtlijnen epv. Versienummering. Datum 19 december Onderwerp Standaarden en richtlijnen Versienummering

Recommend Documents