Versionierung und Kompatibilität

Bei der Weiterentwicklung dieser Spezifikation ist damit zu rechnen, dass nicht alle beteiligten Implementierungen jeweils den aktuellsten Stand der Spezifikation umsetzen. Es ist also dafür zu sorgen, dass Server und Client, die unterschiedliche Versionen der veloconnect-Spezifikation implementieren, weitgehend reibungslos zusammenarbeiten können. Die Weiterentwicklung der Spezifikation wird daher folgenden Regeln unterworfen:

Regel: Versions-Richtlinie

1. Jede veloconnect-Spezifikation wird nach dem Schema {version}.{revision} nummeriert. Hierbei ist {version} die Versionsnummer und {revision} die Revisionsnummer. Die vorliegende Spezifikation hat also die Versionsnummer 1 und die Revisionsnummer 5. Eine Spezifikation ist neuer als eine andere, wenn ihre Versionsnummer größer ist, oder wenn die Versionsnummern übereinstimmen und die Revisionsnummer größer ist.

2. Innerhalb eines Zeitraums von 12 Monaten findet höchstens ein Wechsel der Versionsnummer statt.

3. Die in der Spezifikation definierten Namensräume von Modulen werden alle nach dem Muster urn:veloconnect:{modul-name}-{version}.{revision} bezeichnet. Die Versionsnummer stimmt mit der Versionsnummer der Spezifikation überein. Die Revisionsnummer entspricht der letzten Revision, in der dieses Modul hinzugefügt oder geändert wurde.

4. Ein Modul, das in einer veloconnect Spezifikation {version}.{r1} verwendet wird, wird auch in allen Spezifikationen {version}.{r2} verwendet, wenn r2 größer oder gleich r2 ist.

5. Bei Änderungen an der Spezifikation die eine Abwärtskompatibilität verhindern würden (breaking-change), dürfen diese nur unter einer höheren Versionsnummer veröffentlich werden. Bei Aktualisierung der Revisionsnummer muss die Änderung immer abwärtskompatibel sein.

Für Client und Server hat es unterschiedliche Konsequenzen, wenn sie mit einer Gegenseite kommunizieren, die einen anderen Stand der Spezifikation implementiert. Für die Implementierung von Clients werden einige Empfehlungen ausgesprochen, für Server einige diesbezügliche Regeln formuliert.

Für beide gilt jedoch, dass die XSD-Schemas nicht zur Input-Validierung genutzt werden sollten. Weder Client noch Server wissen die exakte Version der Gegenseite und können daher nicht die korrekte Version des Schemas zur Validierung wählen. D.h. die Schemas sollten nur als Dokumentation betrachtet werden bzw. für interne Tests bei der Umsetzung genutzt werden um die eigene Implementierung zu verifizieren. Zur Laufzeit sollte der Input über eine eigenen Implementierung validiert werden. Dabei kann nicht davon ausgegangen werden, dass der Input 100% der eigenen, gerade genutzten, Schema-Version entspricht.

Empfehlung für Client-Implementierungen

• Die Implementierung sollte keine Annahmen über das Nichtvorhandensein von Elementen oder Attributen machen. Es kann durchaus sein, dass eine neuere Spezifikation z.B. zwischen zwei Kindelementen ein weiteres optionales Element einfügt.

• Ebenso kann es sein, dass für Typen, die als Aufzählung definiert sind, weitere Werte erlaubt werden. Die Implementierung sollte auf diesen Fall gefasst sein und gegebenenfalls einen Hinweis an den Benutzer generieren.

• Da nicht davon auszugehen ist, dass die Server jeweils den neuesten Stand der Spezifikation implementieren, müssen gegebenenfalls auch veraltete Operationen, d.h. Operationen, die in der aktuellen Spezifikation nicht mehr vorgesehen sind, unterstützt werden.

Regel: Abwärtskompatibilität (Server)

Im Umgang mit Clients, die einen älteren Stand der Spezifikation implementieren, muss ein veloconnect-konformer Server folgende Regeln beachten:

1. Sofern eine Anfrage des Client als gültige Anfrage umgesetzt werden kann, ist diese Anfrage gemäß der aktuellen Spezifikation des Servers zu beantworten

2. Andernfalls hat der Server die Wahl, ob die Anfrage gemäß einer früheren Spezifikation beantwortet wird oder ob der Fehlercode 406 zurückgeliefert wird.

Regel: Aufwärtskompatibilität (Server)

Im Umgang mit Clients, die einen neueren Stand der Spezifikation implementieren, muss ein veloconnect-konformer Server folgende Regeln beachten:

1. Sofern eine Anfrage des Client als gültige Anfrage umgesetzt werden kann, ist diese Anfrage gemäß der aktuellen Spezifikation des Servers zu beantworten

2. Andernfalls wird der Fehlercode 405 zurückgeliefert.