xml schema design - trivadis.com · soa guidelines – xml schema design version 1.0 seite 2/46...

SOA Guidelines – XML Schema Design

Version 1.0 Seite 1/46

http://www.ibm.com/developerworks/xml/library/ws-tip-headers/index.html

SOA Guidelines

XML Schema Design

Matthias Furrer Principal Consultant



Dokument Information

Status * Abgeschlossen

Projektname SOA Guidelines

Autor Matthias Furrer

Initiale mfu

Bearbeitende Matthias Furrer

Prüfende Michel Hautle, Guido Schmutz, Markus Zehnder

Genehmigende

Verteiler

* In Arbeit, In Prüfung, Abgeschlossen

Änderungskontrolle, Prüfung, Genehmigung

Version Datum Beschreibung, Bemerkung Name oder Rolle

0.9 29.05.2015 Draft Version Matthias Furrer

1.0 02.07.2015 Finale Version Matthias Furrer



Inhaltsverzeichnis

1 Einführung 6

1.1 XML Version 1.1 .................................................................................................. 6

1.2 Generelle Konventionen die in diesem Dokument verwendet werden .................. 7

1.2.1 Formatierungsarten für zusammengesetzte Wörter bzw. Sätze ........................... 9

2 Ziele 10

2.1 Anforderungen ................................................................................................... 10

2.2 Leitsätze ............................................................................................................ 10

3 Generelle XML Design Regeln 12

3.1 Aufbau von XML Dokumenten ........................................................................... 12

3.1.1 XML Schema ..................................................................................................... 12

3.1.2 XML Dokumentinstanz ....................................................................................... 13

3.2 Schemaweit gültige Standards .......................................................................... 14

3.2.1 Sprache von Typen, Elementen und Attributen .................................................. 14

3.2.2 XML Deklarationen ............................................................................................ 14

3.2.3 Schema Attribute ............................................................................................... 14

3.2.4 Kommentare und Dokumentation ...................................................................... 15

3.3 Verwendung von Namensräumen (Namespaces) .............................................. 16

3.3.1 Schema Namespace ......................................................................................... 17

3.3.2 Element Namespace ......................................................................................... 17

3.3.3 Attribut Namespace ........................................................................................... 18

3.4 Logische und physische Strukturierung von XML Dokumenten ......................... 19

3.4.1 Logische Strukturierung ..................................................................................... 19

3.4.2 No Namespace .................................................................................................. 21

3.4.3 Single Namespace............................................................................................. 21

3.4.4 Multiple Namespace .......................................................................................... 22

3.5 Versionierung von XML Dokumenten ................................................................ 22

4 Einschränkungen für den Schema-Entwurf 23

4.1 Typen- und Struktur Definitionen im Schema ..................................................... 23

4.2 Element-Definitionen im Schema ....................................................................... 23

4.3 Attributs-Definitionen im Schema ....................................................................... 24

4.4 Attribute für die Verwendung in Dokumentinstanzen.......................................... 25

4.4.1 Lokale Typendefinition ....................................................................................... 25

4.4.2 Schema ohne Namensräume ............................................................................ 25

4.4.3 Empty Elements ................................................................................................ 25

5 Erweiterte Regeln zum Design 26



5.1 Lokale vs. Globale Deklaration .......................................................................... 26

5.1.1 Design Patterns ................................................................................................. 26

5.1.2 Design Richtlinien .............................................................................................. 30

5.2 Elemente vs. Typen ........................................................................................... 31

5.2.1 Referenzierung von Komponenten aus anderen Namensräumen ...................... 31

5.3 Attribute vs. Elemente ........................................................................................ 34

6 Namenskonventionen 35

6.1 Namens-Segmente in der Namensgebung von Elementen, Typen und Attributen ........................................................................................................... 37

6.1.1 Suffixe zur Bezeichnung des Datentyps ............................................................. 37

6.1.2 Terminologie der Benennung von Businessobjekten ......................................... 41

7 Links 42

7.1 XML-Spezifikationen .......................................................................................... 42

7.2 Referenzen ........................................................................................................ 43

8 Anhang A – Schema Beispiel 44



Abbildungsverzeichnis

Abbildung 1: Die XML Deklaration ........................................................................................................ 12

Abbildung 2: Deklaration der Schema-Attribute .................................................................................... 12

Abbildung 3: Definition der Strukturen und Elemente ........................................................................... 13

Abbildung 4: XML Dokumentinstanz ..................................................................................................... 13

Abbildung 5: Lokale Deklaration – „Russian Doll” ................................................................................. 26

Abbildung 6: Globale Deklaration – „Salami Slice”................................................................................ 27

Abbildung 7: Globale Deklaration mit Typen – „Venetian Blind” ........................................................... 28

Abbildung 8: Globale Deklaration der Elemente und Typen– „Garden of Eden” .................................. 29



1 Einführung

Extensible Markup Language (XML) ist eine Sprache zur Beschreibung des Inhaltes eines Dokumentformates und dient zur strukturierten Darstellung von Daten in einem maschinell bearbeitbaren Format. XML ist definiert vom in den XML 1.0 Spezifikationen vom World Wide Web Consortium (W3C – http://www.w3.org /).

Die XML Spezifikationen definiert ein XML als „wohlgeformt” (oder englisch „well-formed”) wenn es die definierten Syntax-Regeln einhält. Wird XML zum Datenaustausch verwendet, empfiehlt es sich darüber hinaus Regeln zu definieren, welche die formale Grammatik eines Dokumentes beschreibt und damit die syntaktische Struktur von XML Dokumentinstanzen definiert. Dies geschieht heute am meisten verbreitet mit Hilfe von XML Schema – weitere gebräuchliche – in diesem Dokument jedoch nicht behandelte - Schemasprachen sind Schematron oder RELAX NG. Der Standard definiert ein XML-Dokument als gültig (oder englisch valid), wenn es wohlge-formt ist, den Verweis auf eine Grammatik enthält und das durch die Grammatik beschriebe-ne Format einhält.

1.1 XML Version 1.1

Die Zweite Version von XML – 1.1. wurde 2004 veröffentlicht und enthält einige spezifische Erweiterungen:

Unterstützung von Version 4.0 von Unicode Zusätzliche Zeichen in Namen sind erlaubt Zusätzliche Zeilenende-Zeichen (für EBCDIC Plattformen sind erlaubt)

XML 1.1 ist nicht sehr weit verbreitet und wird nur zur Benutzung empfohlen wenn die spezi-fischen Erweiterungen benötigt werden.

Erschwerend kommt dazu, dass die Spezifikationen für XML 1.1 noch nicht definitiv verab-schiedet sind (http://www.w3.org/TR/xmlschema11-1/ - Stand Juli 2011 „Candiate Recom-mendation”) und noch nicht alle XML-Verarbeitungsprogramme Version 1.1 korrekt verarbei-ten. Daher wird hier generell empfohlen die Version 1.0 einzusetzen.



1.2 Generelle Konventionen die in diesem Dokument v erwendet werden

Sämtliche Richtlinien werden in diesem Dokument zusätzlich in tabellarischer Form be-schrieben, wie nachfolgend dargestellt.

<Identifikations-Code> <Beschreibung der Regel> < Regel-Gruppe>

• Identifikations-Code

Jede Regel, die in dem Dokument beschrieben wird, wird durch einen, innerhalb des Dokumentes eindeutigen Identifikationscode gekennzeichnet. Der Identifikationscode besteht aus einem dreistelligen Präfix und einer vierstelligen Regelnummer im fol-genden Format:

<präfix>- <regel-nummer>

Folgende Präfixe werden zurzeit verwendet :

Präfix Beschreibung

GEN Generelle Entwurfsrichtlinie

NMR Namenskonvention (File, Tag, Namespace, usw.)

BEP Best Practice



Die Regelnummern werden übergreifend vergeben (ausser IBP) und sind nicht geordnet. Die nächste freie Regelnummer ist: 092.

• Beschreibung der Regel

Eine möglichst kurze und prägnante Beschreibung der Regel, mit der Verwendung der un-terschiedlichen Regeltypen im Text

• Regel Gruppe

Die Regeln werden nach den Konventionen, die vom Request for Comment 2119 [REQ_COMM_2119] definiert wurden, in verschiedene, nachfolgend aufgelisteten Gruppen aufgeteilt.

MUST Bedeutet eine absolute Anforderung, die zwingend eingehalten wer-den muss.

MUST NOT Bedeutet ein absolutes Verbot, d.h. es darf auf keinen Fall verwendet werden.

SHOULD Bedeutet, dass es gute Gründe geben kann, die entsprechende Regel zu ignorieren. Die Auswirkungen müssen klar sein und gewichtet werden, bevor ein alternativer Weg beschritten wird.

SHOULD NOT

Bedeutet, dass es gute Gründe geben kann, dass das von der Regel beschrieben Verhalten akzeptabel oder sogar hilfreich ist. Die Auswir-kungen müssen klar sein und gewichtet werden, bevor das entspre-chende Verhalten implementiert wird.

MAY Bedeutet, dass der durch die Regel beschriebene Begriff wirklich optional ist. Es ist Sache des Anwenders, ob er die Regel anwendet oder nicht.



1.2.1 Formatierungsarten für zusammengesetzte Wörte r bzw. Sätze

Folgende Formatierungsarten werden in diesem Dokument verwendet:

o UpperCamelCase (UCC) – Upper Camel Case ist eine Art der Repräsentation von zusammengesetzten Wörtern oder Sätzen, bei der die einzelnen Wörter ohne Zwi-schenraum zusammengefügt werden, wobei jeweils der erste Buchstabe eines Wor-tes in Grossbuchstaben geschrieben werden: „CreditCardExpirationDate”

o LowerCamelCase (LCC) – Lower Camel Case ist eine Art der Repräsentation von zusammengesetzten Wörtern oder Sätzen, bei der die einzelnen Wörter ohne Zwi-schenraum zusammengefügt werden, wobei ausser beim ersten Wort jeweils der ers-te Buchstaben eines Wortes in Grossbuchstaben geschrieben werden: „creditCa-rdExpirationDate”

o LowerDashed (LD) – Lower Dashed ist eine Art der Repräsentation von zusam-mengesetzten Wörtern oder Sätzen, bei der die einzelnen Wörter mit einem Binde-strich-Buchstaben getrennt zusammengefügt werden, wobei alles in Kleinbuchstaben geschrieben wird: „credit-card-expiration-date”



2 Ziele

2.1 Anforderungen

Dieses Dokument bezieht sich insbesondere auf den Einsatz von XML und XML Schema im Zusammenhang mit dem Einsatz in Webservices und Service Orientierten Architekturen. Daher wird auf die Nutzung gewisser im XML-Standard vorhandener Funktionalitäten zur Ableitbarkeit und Erweiterbarkeit von Typendefinitionen bewusst verzichtet – diese umfassen bspw. die Strukturelemente in XML Schema wie: xsd:any , xsd:extension , xsd:redefine .

Obwohl diese zusätzliche Flexibilität in manchen Fällen nützlich sein kann, widersprechen sich diese teilweise mit der Idee von einem verbindlichen und möglichst transparenten kano-nischen Schema, welches bei umfangreicheren Integrationslösungen dringend empfohlen wird. Darüber hinaus unterstützen weiterhin nicht alle XML Sprachen wie XSLT, XQUERY die komplette typbasierende Verarbeitung.

2.2 Leitsätze

Die in diesem Dokument beschriebenen Leitsätze lehnen sich an den Design-Rules Stan-dard von United Nations Centre for Trade Facilitation and El ectronic Business [UN/CEFACT] an, welche u. a. verantwortlich für den internationalen Datenstandard EDIFACT und einer der Initiatoren von ebXML ist.

Insbesondere sind die folgenden Design Principles als Basis für die in diesem Dokument aufgeführten Richtlinien berücksichtigt:

• XML Schema Erzeugung – Die Design Richtlinien unterstützen sowohl die manuelle als auch die automatisierte Erzeugung von Schema Definitionen.

• Austausch und Nutzung in Anwendungen – Die XML Schema und daraus erzeugte XML Dokumentinstanzen sind für eine Vielfalt von Datenaustausch- und Integrations-prozessen verwendbar.

• Tool Verwendung und Support – Das Design von XML Schema ist nicht abhängig von verwendeten Werkzeugen für die Erstellung, Verwaltung oder Verarbeitung von XML Artefakten.

• Lesbarkeit – XML Dokumentinstanzen sind intuitiv lesbar und möglichst klar im Kon-text des Verwendungszwecks.

• Schema Features – Das Design von XML Schema sollte die am häufigsten unter-stützten Features der W3C XML Schema Definition Language Empfehlung verwen-den.

• Technische Spezifikationen – Namenskonventionen und Design Richtlinien basieren auf technischen Spezifikationen mit dem entsprechenden W3C Empfehlungsstatus.

• XML Schema Spezifikationen – Namenskonventionen und Design Richtlinien sind vollkommen konform mit der W3C XML Schema Definition Language Empfehlung.

• Interoperability – Die Anzahl von Möglichkeiten die gleiche Information in einem XML Schema oder Dokumentinstanz darzustellen soll möglichst niedrig gehalten werden.



• Maintenance – Das Design von XML Schema unterstützt und erleichtert die Wartbar-keit.

• Bezug auf andere Namensräume - Abhängigkeit zu anderen Namensräumen werden mit Vorsicht verwendet.



3 Generelle XML Design Regeln

GEN-0001 Das XML Schema MUSS der Standardstruktur folgen, wie sie in Anhang A diese Doku-

mentes definiert ist.

MUST

3.1 Aufbau von XML Dokumenten

Im Folgenden ist exemplarisch der Aufbau von XML Schema Dokumenten sowie XML Do-kumentinstanzen gemäss den Spezifikationen vom World Wide Web Consortium beschrie-ben. Dies soll zum besseren Verständnis dienen, da die nachfolgenden Kapitel jeweils auf die einzelnen hier beschriebenen Namen und Definitionen referenzieren

3.1.1 XML Schema

XML Schema, häufig als XSD abgekürzt, bezeichnet ein XML Vokabular, welches es ermög-licht andere XML Dokumente so zu beschreiben, dass mittels standardisierter Programme getestet werden kann, ob ein gegebenes Dokument den im zugeordneten Vokabular defi-nierten Regeln entspricht.

XML Schema bestehen aus einer XML-Deklaration, der Definition der Schema-Attribute sowie einer nachfolgenden Beschreibung der in referenzierenden XML Dokumentinstanzen zugelassenen Strukturen, Typen und Attributen.

3.1.1.1 XML Deklaration: Die XML Deklaration besteht normalerweise aus der Definition der verwendeten XML-Version, Angaben zur Zeichencodierung sowie allenfalls weiterer Deklarationen.

<?xml version=“1.0” encoding=“UTF-8”?>

Abbildung 1: Die XML Deklaration

3.1.1.2 Deklaration der Schema-Attribute: In den Schema Attributen werden die zu verwendenden Namensräume deklariert sowie weitere Attribute festgelegt, die als Voreinstellung für die im Schema deklarierten Datentypen und Elemente angewendet werden sollen.

<xsd:schema targetNamespace=“http://trivadis.com/sc hema/CreditCard/v1” xmlns:tns=“http://trivadis.com/schema/CreditCard/ v1” xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:soabp-ct=“http://trivadis.com/schema/soabp/ common/UnqualifiedDataType/v1” elementFormDefault=“qualified” attributeFormDefau lt=“unqualified” version=“1.0”> </xsd:schema>

Abbildung 2: Deklaration der Schema-Attribute



3.1.1.3 Definition der Strukturen und Elemente: Die Schemakomponenten sind im xsd:schema Containerelement eingeschlossen und beschreiben im Wesentlichen die gültigen Strukturen, Typen und Attribute für eine referen-zierende Dokumentinstanz. Ebenfalls im Gültigkeitsbereich des Schemas befinden sich Instanzierungen zur Nachverwendung vorhandener Typen-Definitionen sowie Einbindungen von Deklarationen anderer Schemas und/oder Namensräumen.

<xsd:schema …> <xsd:import namespace=“http://trivadis.com/schema/s oabp/common/UnqualifiedDataType/v1” schemaLocation=“UnqualifiedDataType-v1.0.xsd”/> <xsd:element name=“CreditCard” type=“tns:Credit CardType”/> <xsd:complexType name=“CreditCardType”> <xsd:sequence> <xsd:element name=“CardNumber” type=“xsd: string” minOccurs=“1” /> <xsd:element name=“CardholderFirstName” t ype=“xsd:string” minOccurs=“1”/> <xsd:element name=“CardholderLastName” ty pe=“xsd:string” minOccurs=“1”/> <xsd:element name=“ExpirationMonth” type= “soabp-ct:MonthType” minOccurs=“1”/> <xsd:element name=“ExpirationYear” type=“ soabp-ct:MonthType” minOccurs=“1”/> </xsd:sequence> </xsd:complexType> </xsd:schema>

Abbildung 3: Definition der Strukturen und Elemente

3.1.2 XML Dokumentinstanz

Ein XML Dokumentinstanz besteht im Wesentlichen wiederum aus einer XML-Deklaration und beinhaltend nachfolgend die eigentlichen Nutzdaten, welche im Falle einer gewünschten Abhängigkeit von einem XML Vokabular auf das verwendete Schema und den dazugehöri-gen Namensraum referenzieren.

<?xml version=“1.0” encoding=“UTF-8” ?> <CreditCard xmlns:xsi=“http://www.w3.org/2001/XMLSc hema-instance” xsi:schemaLocation=“http://trivadis.com /schema/CreditCard/v1/CreditCard.xsd” xmlns=“http://trivadis.com/schema/Credi tCard/v1”> <CardNumber>4059 1100 0027 9143</CardNumber> <CardholderFirstName>Hans</CardholderFirstName> <CardholderLastName>Muster</CardholderLastName> <ExpirationMonth>09</ExpirationMonth> <ExpirationYear>14</ExpirationYear> </CreditCard>

Abbildung 4: XML Dokumentinstanz



3.2 Schemaweit gültige Standards

3.2.1 Sprache von Typen, Elementen und Attributen

Grundsätzlich ist XML in der Namensgebung von Typen, Elementen und Attributen offen. Aus Gründen der Wiederverwendbarkeit und zum breiteren Verständnis sollten die Element- und Attributnamen in englischer Sprache vergeben werden.

Namensgebung in jeweiliger Landessprache sollten nur auf expliziten Wunsch verwendet werden.

GEN-002 Alle Typen, Elements- und Attributsnamen SOLLTEN in englischer Sprache im XML

Schema definiert werden.

SHOULD

3.2.2 XML Deklarationen

GEN-003 Die XML Deklarationen für Dokumentinstanzen MUSS zwingend vorhanden sein.

Beispiel: <?xml version=“1.0” encoding=“UTF-8” ?>

MUST

3.2.2.1 XML Version

GEN-004 Jedes XML Schema MUSS die XML Version 1.0 verwenden. MUST

3.2.2.2 Character Set

GEN-005 Jedes XML Schema MUSS für die Zeichencodierung mindestens „UTF-8” verwenden. MUST

GEN-006 Falls zwingende Gründe vorhanden sind KANN „UTF-16” verwendet werden. MAY

3.2.3 Schema Attribute

3.2.3.1 Allgemein

GEN-007 Der xsd Präfix MUSS zwingend definiert werden und auf den folgenden Namespace

verweisen: http://www.w3.org/2001/XMLSchema .

MUST

GEN-008 Jedes XML Schema Dokument MUSS einen Target-Namespace über das

xsd:targetNamespace Attribut definieren.

MUST

GEN-009 Jede xsd:schemaLocation Attribut-Deklaration innerhalb eines XML-Schemafiles

MUSS eine URL enthalten, die über einen relativen Pfad aufgelöst werden kann.

MUST

3.2.3.2 Voreinstellungen

BEP-010 Das xsd:elementFormDefault Attribut MUSS deklariert sein und der Wert immer

auf qualified gesetzt werden.

MUST

BEP-011 Das xsd:attributeFormDefault MUSS deklariert sein und der Wert immer auf

unqualified gesetzt werden.

MUST

BEP-012 Das xsd:finalDefault Attribut SOLLTE auf #all gesetzt werden als Voreinstel-

lung des final Attributes für Elemente und komplexe Typen, um die Erweiterung oder

Einschränkung von Typen im Schema selber zu verhindern

Beispiel: finalDefault=“#all”

SHOULD

BEP-013 Das xsd:blockDefault Attribut SOLLTE auf #all gesetzt werden als Voreinstel-

lung des block Attributes für Elemente und komplexe Typen, von Typen um die Erwei-

terung oder Einschränkung in instanzierten Dokumenten durch Erweiterung, Ersetzung

oder Einschränkung zu verhindern

Beispiel: blockDefault=“#all”

SHOULD

3.2.3.3 Schema-Version

BEP-014 Das xsd:schema Versionsattribut MUSS immer deklariert werden.

Beispiel: version=“1.6”

MUST

3.2.4 Kommentare und Dokumentation

GEN-015 Jedes XML Schemafile MUSS einen Kommentar enthalten, welche dem folgenden

Format entspricht :

  

Im Anhang A befindet sich ein komplettes Beispiel der zu verwendeten Kommentare.

MUST



GEN-016 Jedes XML Schemafile SOLLTE einen Kommentar enthalten, welche dem folgenden

Format entspricht.

<xsd:annotation>

<xsd:documentation lang=“EN”>

This Schema will be used to process Credit Ca rds

</xsd:documentation>

</xsd:annotation>

Optional kann das source= Attribut verwendet werden, beispielsweise mit einer

Referenz auf die Ablage einer Dokumentation .

source=“http://trivadis.com/schema/CreditCard/v1/do cu.pdf”>

SHOULD

BEP-017 Bei der Verwendung des documentation Elementes SOLLTE die Sprache immer über

das lang Attribut Qualifiziert werden.

SHOULD

3.3 Verwendung von Namensräumen (Namespaces)

Namensräume in XML werden dazu verwendet um Elemente, Typen und Attribute in XML Dokumenten eindeutig adressieren zu können. Das heisst, Namespaces schaffen die Grund-lage um das Vokabular eines XML-Dokumentes eindeutig zu identifizieren - und um in einem einzelnen Dokument mehrere dieser Vokabulare zu mischen oder zu vereinigen.



3.3.1 Schema Namespace

BEP-018 Schema ohne Namensräume DUERFEN NICHT verwendet werden. MUST NOT

BEP-019 Die Möglichkeit des Default-Namespace DARF NICHT verwendet werden. Sowohl

der XML Schema wie auch der Target-Namespace müssen explizit qualifiziert wer-

den.

Beispiel:

<xsd:schema

targetNamespace=“http://trivadis.com/schema/CreditC ard/v1”

xmlns :tns =“http://trivadis.com/schema/CreditCard/v1”

…

</xsd:schema>

MUST

BEP-020 Als einzige Ausnahme zur Regel BEP-019 KANN zur Vereinfachung der Default-

Namespace auf den Namespace der XML Schema Definition gesetzt werden..

Beispiel:

<xsd:schema

targetNamespace=“http://trivadis.com/schema/Credit Card/v1”

xmlns=“http://www.w3.org/2001/XMLSchema”

…

</xsd:schema>

MAY

NMR-021 Der Target-Namespace im Schema MUSS immer die Major-Versionsnummer bein-

halten

Beispiel: targetNamespace=“http://trivadis.com/schema/CreditC ard/ v1 ”

MUST

NMR-022 Die folgenden Namespace-Präfixe MUESSEN bei der Deklaration der W3C Namens-

räume verwendet werden:

xsd =http://www.w3.org/2001/XMLSchema

xsi =http://www.w3.org/2001/XMLSchema-instance

xsl = http://www.w3.org/1999/XSL/Transform

MUST

NMR-023 Für die Deklaration des Targetnamespace MUSS immer das Prefix tns verwendet

werden.

MUST

3.3.2 Element Namespace

BEP-024 Alle Elemente MUESSEN über einen Namespace qualifiziert sein.

Dies wird per Default über das Schema Attribut elementFormDefault=““qualified”

eingestellt.

MUST



3.3.3 Attribut Namespace

BEP-025 Global definierte Attribute (Attribute die auf der obersten Ebene im Schema dekla-

riert worden sind und damit wiederverwendbar sind) MUESSEN über einen Name-

space qualifiziert sein.

MUST

BEP-026 Nicht global definierte Attribute DUERFEN NICHT über einen Namespace qualifiziert

sein.

Dies wird per Default über das Schema Attribut attributeForm-

Default=““unqualified” eingestellt.

Aufgrund dieser Voreinstellung führt folgende Definition in der importierten Sche-

ma Definition:

<xsd:element name=“AttributeTestElement” type=“AttributeTestType”/> <xsd:attribute name=“globalAttribute”/> <xsd:complexType name=“AttributeTestType”> <xsd:sequence> <xsd:element name=“String1” type=“xsd:string” / > <xsd:element name=“String2” type=“xsd:string” / > </xsd:sequence> <xsd:attribute name =“localAttribute” type=“xsd:s tring” /> </xsd:complexType>

zu diesem XML Instanzdokument:

<p:AttributeQualifying p:globalAttribute =“ v1 ”

xmlns:p=“http://www.example.org/MASTER” xmlns:p1=“http://www.example.org/attribute” … “>

<p1:AttributeTestElement localAttribute =“ local ”>

<p1:String1> String1 </p1:String1>

<p1:String2> String2 </p1:String2>

</p1:AttributeTestElement>

</p:AttributeQualifying>

MAY NOT



3.4 Logische und physische Strukturierung von XML D okumen-ten

Die XML Spezifikationen erlauben es, die Definition eines Schemas in mehreren physischen Dateien zu verwalten und diese zu einem logischen Dokument – im gleichen oder unter-schiedlichen Namensräumen – zusammenzuführen.

Nicht nur, aber insbesondere bei der Umsetzung eines kanonischen Schema (Canonical Schema) in einer SOA können diese Konzepte zur Modularisierung besonders hilfreich eingesetzt werden, um ein wiederverwendbares und gemeinsam nutzbares Vokabular von Entitäts- und Datendefinitionen zur Verfügung zu stellen.

3.4.1 Logische Strukturierung

Grundsätzlich wird empfohlen, „Kern-Entitäten” für die oberste Hierarchie-Ebene zu definie-ren. Diese können beispielsweise sein: „Customer”, „Order”, „Invoice”. Für die nächste Ebe-ne können dann wiederverwendbare Elemente wie „Address”, „AccountInfo”, „PaymentInfo” definiert werden - welche wiederum Definitionen von allgemeineren Elementen beziehen können – welche dann in den Kern-Entitäten referenziert werden.

BEP-027 Ein Schemafile SOLLTE für jede Kernentität erzeugt werden. SHOULD

BEP-028 Ein XML-Schemafile für eine Kernentität DARF NICHT wiederverwendbare Konstruk-

te definieren, die über ein separates XML Schemafile mittels einem xsd:include

oder xsd:import referenziert werden können.

Dies bedeutet, in diesem speziellen Fall darf nur genau ein globales Element defi-

niert werden und das Schema muss nach dem „Russian Doll” Design Pattern imple-

mentiert werden. Referenzierung von Elementen aus anderen Namespace sind

jedoch erlaubt.

<xsd:element name= “CreditCardEntity” > <xsd:complexType> <xsd:sequence> <xsd:element name= “id” type= “xsd:long” /> <xsd:element name= “descriptionText” minOccurs= “0” > <xsd:simpleType> <xsd:restriction base= “xsd:string” > <xsd:maxLength value= “50” /> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element ref= “cre:CreditCard” /> </xsd:sequence> </xsd:complexType>

</xsd:element>

MUST NOT

BEP-029 Deklaration von Listenelementen (Collections) MUESSEN immer im gleichen Sche-

mafile erfolgen, wie die Haupt-Elemente (bspw. Entitäten) welche diese beinhalten.

MUST



Dabei sollte berücksichtigt werden, dass eine feinere Granularität in der Aufteilung zwar die Wiederverwendbarkeit erhöht, auf der anderen Seite dadurch jedoch auch die gegenseitigen Abhängigkeiten steigen und damit Änderungen an einem Objekt unter Umständen grössere Auswirkungen auf mehrere Anwendungen haben.

BEP-030 Die Abhängigkeiten und Referenzierungen der Schema untereinander SOLLTEN

möglichst gering gehalten werden. Ein Schemafile sollte idealerweise nicht Abhän-

gigkeiten über mehr als 3 oder 4 Hierarchiestufen haben.

Beispiel: „Customer” referenziert auf „Address”; „Address” referenziert auf „Com-

mon”. Im Schema für „Common” werden jedoch keine weiteren Elemente von

weiteren Schemas mehr eingebunden.

SHOULD

NOT

3.4.1.1 Common Schema Zur vereinfachten Wiederverwendung wird für allgemein verwendete Datentypen ein eigenes Schema – entweder pro Anwendungsdomäne oder übergreifend – erstellt.

BEP-031 Ein eigenes Schemafile MUSS definiert werden, für die Definition von Typen, welche

Kandiaten zur häufigen Wiederverwendung als einzelne Elemente sind. Dabei muss

je ein Schema für Qualifizierte und Unqualifizierte Typen erstellt werden.

Qualifizierte Typen Types mit Restriktionen wie bspw. EMailAddress, So-

cialSecurityNumber

Unqualifizierte Typen Types ohne Restriktionen, die jedoch voraussichtlich zu

einem späteren Zeitpunkt erweitert werden.

Bei grösseren Projekten, sollte dabei ein eigenes Common Schema pro Anwen-

dungsdomäne– z.B. Accounting, Orders, Master Data - erstellt werden.

MUST

3.4.1.2 Enumerations Um die Auswirkungen auf referenzierende Schema oder Anwendungen bei allfälligen Ände-rungen an erlaubten, bzw. eingeschränkten Feldinhalten zu minimieren, werden Typen mit Enumerations in einem eigenen Schema definiert.

BEP-032 Ein eigenes Code-List XML Schemafile SOLLTE definiert werden, für die Definition

von Typen, die Enumerations beinhalten. Jeder Typ muss dabei in einem eigenen

Schema definiert sein.

SHOULD

3.4.1.3 Speicherort der XML Schema Das Deployment von XML Schema sollte immer in einen physischen Pfad erfolgen, welcher den logischen Aufbau sowie die Anwendungsdomäne repräsentiert.

Diese Struktur sollte auch aus dem verwendeten Namensraum ersichtlich sein und sollte so aufgebaut werden, dass sie möglichst einfach über einen relativen Pfad aufgelöst werden kann.



BEP-033 Der physische Speicherort der Schemadefinition SOLLTE dem folgenden Pattern

gehorchen:

URI scheme://<hostname>/[:<port>]/<domain>/<schema type >

• scheme – Bezeichnung des Zugriffsprotokolls: http | file

• port – Angabe der Portnummer falls nicht Default des verwendeten Pro-

tokolls

• hostname – Qualifizierter Hostname unter dem der angegebene Pfad er-

reichbar ist.

• domain – ein Bezeichner der Geschäftseinheit oder definierten SOA Do-

mäne zu der die Schemadefinition logisch zugeordnet wird.

• schema type – ein Token, welcher den Typ des XML Schema Dokumen-

tes indentifiziert: schema | codelist | common | wsdl

Beispiele:

� http://trivadis.com/Accounting/common

� http://trivadis.com/Accounting/schema

� http://trivadis.com/Accounting/wsdl

SHOULD

3.4.2 No Namespace

Schema-Definitionen müssen immer über einen Namespace qualifiziert sein.

BEP-034 Jedes Schema MUSS zwingend einen Targetnamespace deklarieren.

Siehe auch GE-018.

MUST

Das Weglassen von Namespaces um diese dann auf der obersten Referenzierungsebene – bspw. Schemadefinition der Kern-Entität oder WSDL – unter einem globalen Namespace wie http://www.myCompany.org zusammenzuführen ist nicht erlaubt.

3.4.3 Single Namespace

Das xsd:include Element wird verwendet wenn ein grosses Schema in mehrere kleine - und möglicherweise wiederverwendbare - Teile aufgebrochen werden soll. Dabei müssen alle Deklarationen der eingelesenen Dateien den gleichen Targetnamespace wie das einlesende Dokument verwenden.

BEP-035 Ein Objekt das mittels xsd:include in den gleichen Namensraum eingebunden wird,

DARF NICHT in noch weiteren Objekten verwendet werden.

MUST

NOT

Single Namespace sollte nur in Ausnahmefällen verwendet werden, um grössere Schema zur besseren Übersicht in mehrere physische Dateien aufzuteilen. Definitionen von Typen die mehrfach – bspw. in verschiedenen Entitäten - verwendet werden, müssen immer in einem eigenen Namensraum deklariert werden.



3.4.4 Multiple Namespace

Das xsd:import Element erlaubt die Referenz auf Schemas, die in einem anderen Namens-raum deklariert sind. Damit werden in einem einlesenden Dokument die Deklarationen ande-rer Schemas eingelesen, sodass deren Inhalte referenziert werden können.

BEP-036 Mehrfach verwendete Objekte, die von mehreren Namensräumen referenziert werden

– wie z.B. „Address” - MUESSEN immer in einem eigenen Namensraum deklariert und

mit xsd:import eingebunden werden.

MUST

Die Definition von Elementen und Typen die mehrfach verwendet werden, müssen immer in eigenem Namensraum deklariert werden.

3.5 Versionierung von XML Dokumenten

Der Versionsname von XML Dokumenten setzt sich immer aus einer Major-Release Num-mer und einer Minor-Release Nummer zusammen.

• major – Major-Versionsnummer

• minor – Minor Versionsnummer

Dabei gilt zwingend immer der Grundsatz: Neue Releases innerhalb einer Minor-Versionsnummer sind immer

abwärtskompatibel – das heisst diese dürfen keine Modifikationen enthalten, welche die Validierung innerhalb

der gleichen Major-Versionsnummer beeinträchtigen. Konkret heiss dies, dass XML Dokumentinstanzen,

welche aufgrund eines früheren Schemas des gleichen Major-Release erstellt wurden nach wie vor gültig sein

müssen.

BEP-037 Der Wert der XML-Schema Major-Versionsnummer MUSS ein Wert > 0 sein. MUST

BEP-038 Eine Minor-Versionsänderung MUSS sich darauf beschränken, neuen optionalen XML

Inhalt zu definieren, bestehenden XML Inhalt zu erweitern oder optionale Refinements.

MUST

BEP-039 Eine Minor-Versionsänderung DARF NICHT einen existierenden XML Schema Artefakt

umbenennen.

MUST

NOT

BEP-040 Änderungen in Minor-Versionen DUERFEN NICHT die semantische Kompatibilität mit

Vorgängerversion verletzten, die die gleiche Major-Version aufweisen.

MUST

NOT

BEP-041 Ein XML Schema MUSS seine eigene Version anpassen, wenn ein referenziertes, exter-

nes XML Schema auf eine neue Version geändert wird.

MUST



4 Einschränkungen für den Schema-Entwurf

Um eine maximale Interoperabilität von XML Dokumenten zu gewährleisten, sind zusätzlich zur generellen Struktur eines XML Schema einige zusätzliche Einschränkungen notwendig,.

4.1 Typen- und Struktur Definitionen im Schema

4.1.1.1 Gemischter Inhalt BEP-042 Mixed Content DARF NICHT verwendet werden.

Dies ist nicht zugelassen:

<wrapper> <element> value </element> other content

</wrapper>

MUST NOT

BEP-043 Das Attribut xsd:mixed DARF NICHT verwendet werden. MUST NOT

4.1.1.2 Überschreiben von Definitionen im Schema BEP-044 Das xsd:redefine Element DARF NICHT verwendet werden. MUST NOT

BEP-045 Das xsd:extension Element DARF NICHT verwendet werden. MUST NOT

4.1.1.3 Externe Programm oder Verarbeitungs-Instruk tionen BEP-046 Das xsd:notation Element DARF NICHT verwendet werden. MUST NOT

4.1.1.4 Kompositoren in Modellgruppen BEP-047 Der Kompositor <all> in Model Groups SOLLTE NICHT verwendet werden. SHOULD

NOT

4.2 Element-Definitionen im Schema

4.2.1.1 Empty Elements Um Laufzeitfehler bei Transformationen und Zuordnungen zu vermeiden, bzw. zusätzliche Errorhandling Blöcke zu minimieren, werden leere Elemente nicht zugelassen.

BEP-048 Empty Elements DUERFEN NICHT verwendet werden. MUST NOT

BEP-049 Das xsd:nillable Attribut DARF NICHT verwendet werden. MUST NOT



4.2.1.2 Deklaration Vorkommnisse von Elementen BEP-050 Elemente SOLLTEN mit Occurance-Indikatoren deklariert werden.

Beispiel: <element name=“firstName” minOccurs=“1” maxOccurs=“1” />

SHOULD

BEP-051 Elemente vom DatenTyp xsd:string mit einer optionalen Verwendung im

Schema (minOccurs=“0” ) SOLLTEN immer mit einer Längenrestriktion deklariert

werden.

SHOULD

4.2.1.3 Nicht typisierte Elemente BEP-052 Das xsd:any Element SOLLTE NICHT verwendet werden. In Schemadeklaration

welche gegen aussen publiziert werden (nicht ausschliesslich von der eigenen

Anwendung verwendet) , dürfen diese nicht verwendet werden.

SHOULD

NOT

BEP-053 Der DatenTyp xsd:anySimpleType für Elementsdefinitionen Elementdefiniti-

onen DARF NICHT verwendet werden.

MUST NOT

BEP-054 Bei Elementsdeklarationen mit Referenzierung auf einen Typ MUSS das type=

Attribut immer angegeben und definiert werden.

MUST

4.2.1.4 Default Werte Im Sinne der Nachvollziehbarkeit von Tests sollten durch Validierungsfunktionen keine Werte im XML Instanzdokument ersetzt werden.

BEP-055 Das xsd:default Attribut für Elementdefinitionen SOLLTE NICHT verwendet

werden

SHOULD

NOT

4.2.1.5 Ersetzungsgruppen BEP-056 Das xsd:substitutionGroup Attribut für Elementdefinitionen DARF NICHT

verwendet werden

MUST NOT

4.2.1.6 Datentypen BEP-057 Der xsd:ID/xsd:IDREF/xsd:IDREFS Datentyp DARF NICHT verwendet

werden.

MUST NOT

4.3 Attributs-Definitionen im Schema

4.3.1.1 Nicht typisierte Attribute BEP-058 Das xsd:anyAttribute Attribut DARF NICHT verwendet werden. MUST NOT

4.3.1.2 Default Werte Im Sinne der Nachvollziehbarkeit von Tests sollten durch Validierungsfunktionen keine Werte im XML Instanzdokument ersetzt werden.



BEP-059 Das xsd:default Attribut für Attributsdefinitionen SOLLTE NICHT verwendet

werden

SHOULD

NOT

4.4 Attribute für die Verwendung in Dokumentinstanz en

4.4.1 Lokale Typendefinition

BEP-060 Lokale Typendefinitionen im XML-Dokument DUERFEN NICHT verwendet werden. MUST NOT

BEP-061 Das xsi:type Attribut DARF NICHT verwendet werden. MUST NOT

4.4.2 Schema ohne Namensräume

BEP-062 Das xsi:noNamespaceSchemaLocation Attribut DARF NICHT verwendet

werden.

MUST NOT

4.4.3 Empty Elements

BEP-063 Das xsi:nil=“true” Attribut SOLLTE NICHT verwendet werden. SHOULD

NOT



5 Erweiterte Regeln zum Design

5.1 Lokale vs. Globale Deklaration

Die Sprachelemente von XML Schema erlauben sowohl die Deklaration von globalen als auch lokalen Elementen und Typen. Eine Komponente eines XML Schemas wird als global bezeichnet, wenn diese als unmittelbares „Child” von <schema> definiert ist, wohingegen lokale Komponenten verschachtelt in einer anderen Komponente deklariert sind (z.B. inner-halb eines Elementes als <complexType>).

5.1.1 Design Patterns

5.1.1.1 Lokale Deklaration - „Russian Doll Design” Bei diesem Pattern wird nur ein globales Element definiert, alle anderen Elemente sind lokal definiert, das Schema bündelt alle Elemente zu einer gültigen Deklaration

<xsd:element name=“CreditCard”> <xsd:complexType> <xsd:sequence> <xsd:element name=“CardNumber” type=“xsd: string” minOccurs=“1” /> <xsd:element name=“CardholderFirstName” t ype=“xsd:string” minOccurs=“1”/> </xsd:sequence> </xsd:complexType> </xsd:element>

Abbildung 5: Lokale Deklaration – „Russian Doll”

5.1.1.1.1 Charakteristik

� Beinhaltet nur ein globales Element, alle anderen Elemente sind lokal definiert � Wiederverwendbarkeit nur für das Root Element gegeben � Erlaubt die Steuerung der Namespacesichtbarkeit auf globaler Ebene durch entspre-

chende Definition von „elementFormDefault ” – Namespaces können gegen aussen verborgen werden

� Schema muss in einem File definiert werden



5.1.1.2 Globale Deklaration - „Salami Slice Design” In diesem Design Pattern werden alle Elemente als globales Element definiert. Da es keine verschachtelten Element-Deklarationen gibt, können alle Elemente über das gesamte Sche-ma wiederverwendet werden.

<xsd:element name=“cardNumber” type=“xsd:string”/> <xsd:element name=“cardholderFirstName” type=“xsd:s tring”/>

<xsd:element name=“CreditCardType”> <xsd:complexType> <xsd:sequence> <xsd:element ref=“cardNumber” minOccurs=“ 1” />

<xsd:element ref=“cardholderFirstName” min Occurs=“1”/> </xsd:sequence> </xsd:complexType> </xsd:element>

Abbildung 6: Globale Deklaration – „Salami Slice”


� Alle Elemente werden global deklariert � Erlaubt die Wiederverwendbarkeit von Elemente auch in anderen Dokumenten � Kein „hidden Namespace” gegen aussen möglich – Namespace ist in Dokumentin-

stanzen immer sichtbar.



5.1.1.3 Globale Deklaration durch Typen - „Venetian Blind Design” Wie beim „Salami Slice Design” werden in diesem Pattern Definitionen global deklariert, im Unterschied dazu existiert aber nur ein globales Element. Für die globalen Deklarationen werden hier Typen anstelle von Elementen verwendet.

<xsd:simpleType name=“CardNumberType”> <xsd:restriction base=“xsd:string”> </xsd:restriction> </xsd:simpleType> <xsd:simpleType name=“CardholderFirstNameType”> <xsd:restriction base=“xsd:string”> <xsd:minLength value=“1”/> </xsd:restriction> </xsd:simpleType> <xsd:element name=“CreditCard”> <xsd:complexType> <xsd:sequence> <xsd:element name=“CardNumber” type=“Car dNumberType” minOccurs=“1” /> <xsd:element name=“CardholderFirstName” type=“CardholderFirstNameType” minOccurs=“1”/> </xsd:sequence> </xsd:complexType> </xsd:element>

Abbildung 7: Globale Deklaration mit Typen – „Venetian Blind”


� Beinhaltet nur ein globales Element � Individuelle Komponenten werden als Typen definiert � Erlaubt die Wiederverwendbarkeit aller Typen und des globalen Root Elements � Erlaubt die Aufteilung der Definitionen in mehrere Files � Sichtbarkeit des Namespace kann auf Schemaebene über „elementFormDefault ”

Switch gesteuert werden � Limitierte Kapselung durch Exponierung der Typen



5.1.1.4 Globale Deklaration der Elemente und Typen - „Garden of Eden” Hierbei handelt es sich um eine Kombination des „Venetian Blind” und des Salami Slice” Patterns. Alle Elemente und Typen werden global definiert.

<xsd:element name=“CardNumber” type=“CardNumberType ”/> <xsd:element name=“CardholderFirstName” type=“Cardh olderFirstNameType”/> <xsd:element name=“CreditCard” type=“CreditCardType ”/> <xsd:simpleType name=“CardNumberType”> <xsd:restriction base=“xsd:string”/> </xsd:simpleType> <xsd:simpleType name=“CardholderFirstNameType”> <xsd:restriction base=“xsd:string”> <xsd:minLength value=“1”/> </xsd:restriction> </xsd:simpleType> <xsd:complexType name=“CreditCardType”> <xsd:sequence> <xsd:element ref=“CardNumber” minOccurs=“1” /> <xsd:element ref=“CardholderFirstName” min Occurs=“1”/> </xsd:sequence> </xsd:complexType>

Abbildung 8: Globale Deklaration der Elemente und Typen– „Garden of Eden”


� Alle Elemente und Typen werden global deklariert � Erlaubt die Wiederverwendbarkeit von Typen und Elementen � Erlaubt die Aufteilung der Definitionen in mehrere Files � Limitierte Kapselung durch Exponierung der Typen



5.1.2 Design Richtlinien

In der Literatur finden sich teilweise unterschiedliche Interpretationen der oben beschriebe-nen Patterns. In einigen Quellen wird das „Venetian Blind” Pattern beschrieben mit der Rest-riktion – so wie oben wiedergegeben - nur ein einziges globales Element zu deklarieren. In anderen Beschreibungen existiert diese Restriktion nicht und es wird dabei empohlen, zu-sätzlich die voraussichtlich wiederzuverwendenden Komponenten selektiv als Elemente zu definieren. In anderen Quellen wird dieses Design Modell auch als „Hybrid” bezeichnet.

Um eine möglichst hohe Wiederverwendbarkeit gewährleisten zu können und da gemäss vorliegenden Richtlinien zwingend die Qualifizierung von Elementen vorgegeben ist, sollten im Design von XML Schema das Hybrid Design Modell implementiert werden.

BEP-064 Das XML Schema Design SOLLTE dem Hybrid-Ansatz zwischen „Venetian Blind” und

„Garden of Eden” Pattern folgen. Typen werden global deklariert, Elemente welche

voraussichtlich wiederverwendet werden, sind dabei ebenfalls im globalen Namens-

raum definiert. Es müssen dabei jedoch nicht zwingend alle Elemente global dekla-

riert werden.

SHOULD

BEP-065 Komplexe Typen SOLLTEN immer benannt werden und nie inline (innerhalb eines

Elementes) definiert werden. SHOULD

BEP-066 Globale Elemente und Attribute SOLLTEN immer die type= Form verwenden und

keine anonymen Typen enthalten. SHOULD

BEP-067 Elemente innerhalb von Model Groups (choice oder sequence ) SOLLTEN immer

die ref= Form und nie die type= Form verwenden.

SHOULD

BEP-068 Die Definition von einfachen Typen (xsd:simpleType ) KANN anonyme einfache

Typendefinitionen beinhalten. Die Definition des einfachen Typen selber jedoch,

SOLLTE NICHT anonym in einem Attribut oder Element erfolgen.

MAY /

SHOULD

NOT



5.2 Elemente vs. Typen

Grundsätzlich können globale Komponenten sowohl als Types wie auch als Elemente im Schema definiert werden. Allgemein gilt als Best Practice im Zweifelsfall einen Typen zu definieren, da diese flexibler definiert werden können und Elemente nachträglich auf einfa-che Weise noch ergänzt werden können. Es ist weitgehend etabliert, Komponenten welche nicht vorgesehen sind als Elemente in XML Dokumentinstanzen zu erscheinen, ebenfalls als komplexe Type zu implementieren.

Sowohl Oracle Service Bus (OSB) wie auch BPEL 2.0 unterstützen die Definition von Variab-len basierend auf globalen Elementen und Typen, während hingegen BPEL 1.1 nur Variab-len von globalen Elementen zulässt.

GEN-069 Jedes XML Schema Dokument, welches direkt von einer WSDL Definition eingebunden

wird, MUSS auf oberster Ebene die Deklaration eines Root Elements enthalten, auf

welches in der Message-Definition des Services referenziert werden kann.

MUST

5.2.1 Referenzierung von Komponenten aus anderen Na mensräumen

Falls Komponenten aus anderen Namensräumen verwendet warden, soll dessen Namens-raum immer auf der Elementebene ersichtlich bleiben. Dies wird erreicht indem solche im-portierten Objekte in der ref= und nicht der type= Form eingebunden werden.



BEP-070 Wenn Komponenten von anderen Namensräumen wiederverwendet werden,

MUESSEN diese immer als Element – und nicht als Typen - referenziert und im Her-

kunftsdokument entsprechend definiert werden. Andernfalls erhält das übergeordnete

Element den Namespace des referenzierenden Schemas.

Beispiel:

<xsd:sequence> <xsd:element name=“id” type=“xsd:long”/> <xsd:element ref= “ cca:CreditCard ”/> </xsd:sequence>

Führt zu folgender Qualifizierung des Namensraums im XML Instanzdokument:

<?xml version=“1.0” encoding=“UTF-8”?> <mas:CreditCardEntity xmlns:mas=“http://www.example .org/Master” xmlns:cre=“http://www.example.org/CreditCard” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instanc e” xsi:schemaLocation=“http://www.example.org/Master M aster.xsd “> <mas:id> 789 </mas:id> < cre: CreditCard> <cre:CardNumber> 1234 </cre:CardNumber> <cre:CardholderFirstName> Hans</cre:CardholderFirstName> </ cre: CreditCard>

</mas:CreditCardEntity>

MUST

BEP-071 Falls das gleiche Element eines anderen Namensraums innerhalb von Model Groups

mehrfach verwendet wird, MUSS dieses innerhalb eines Types, welcher wiederum

einen eindeutigen Namen hat, definiert werden.

Beispiel:

<xsd:element name=“CreditCardInfo”> <xsd:complexType> <xsd:sequence> <xsd:element name=“id” type=“xsd:long”/> <xsd:element name=“ MainCreditCard ” minOccurs=“1”> <xsd:complexType> <xsd:sequence> <xsd:element ref=“ cre:CreditCard ”/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name=“ AltCreditCard ” minOccurs=“0”> <xsd:complexType> <xsd:sequence> <xsd:element ref=“ cre:CreditCard ”/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name=“ OldCreditCards ” minOccurs=“0” maxOccurs=“unbounded”> <xsd:complexType> <xsd:sequence> <xsd:element cre=“ cre:CreditCard ”/> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:sequence> </xsd:complexType>

</xsd:element>

MUST



BEP-072 Wenn Komponenten des gleichen Namensraumes wiederverwendet werden, SOLLTEN

diese immer mit der Type= Form referenziert werden.

SHOULD



5.3 Attribute vs. Elemente

Aus Gründen der Klarheit und Abgrenzung – sowie der leichteren Erweiterbarkeit – wird hier empfohlen, Attribute generell nur für Metadaten zu verwenden. Als Metadaten gelten dabei Informationen über die im Dokument enthaltenen Daten oder das Dokument selber so wie beispielsweise die Versionsnummer des Schemas oder alternative Feldbeschreibungen.

BEP-073 Für die Repräsentation von Daten MUESSEN Elemente verwendet werden - und nicht

Attribute.

MUST

BEP-074 Attribute SOLLTEN nur für Metadaten verwendet werden SHOULD



6 Namenskonventionen

NMR-075 Die Namen der Elemente, Attribute und Typen SOLLTEN aus Wörtern gebildet werden,

die im definierten Wörterbuch zu finden sind.

SOLLTE

NMR-076 Für den Namen von Attributen MUSS LowerCamelCase (LCC) verwendet werden. MUST

NMR-077 Für den Namen der Elementen und Typen MUSS UpperCamelCase (UCC) verwendet

werden.

MUST

NMR-078 Dem Namen eines ComplexType und eines SimpleType MUSS der Suffix Type ange-

hängt werden.

Bespiel: AddressType

MUST

NMR-079 Dem Namen von Elementen oder Typen, welche wiederum Iterationen mit dem Attri-

but maxOccurs>“1” von Elementen beinhalten, SOLLTE der Suffix Collection

angehängt werden.

Beispiel:

<xsd:complexType name=“ PersonsCollection ”>

<xsd:sequence>

<xsd:element maxOccurs=unbounded” ref=Person”/>

<xsd:sequence>

</xsd:complexType>

Alternativ kann der Plural des im Listenelement definierten Element verwendet werden

– z.B. Persons . Allerdings sollt dies innerhalb einer Domäne konsistent gehandhabt

werden.

SHOULD

NMR-080 Sämtliche Namen SOLLTEN eine Maximallänge von 35 Zeichen nicht überschreiten. SHOULD

NMR-081 Element-, Attribut- und Typ-Namen MUESSEN innerhalb eines Namensraums eindeutig

sein.

MUST

NMR-082 Underscore (_), Punkte (.) und Bindestrich (-) Zeichen SOLLTEN NICHT verwendet

werden oder SOLLTEN für spezielle Anforderungen reserviert sein.

SHOULD

NOT

NMR-083 Elemente, Attribute und Typen MUESSEN in Singularform definiert werden, ausser das

Konzept selbst existiert nur Pluralform (z.B. GoodsQuantity).

MUST

NMR-084 Die Namen der XML Elemente, Attribute und Typen MUESSEN aus Kleinbuchstaben [a-

z], Grossbuchstaben [A-Z], Zahlen [0-9] und Underscore-Zeichen [_] gebildet werden.

MUST

NMR-085 Die Namen der XML Elemente, Attribute und Typen DUERFEN NICHT Akronyme, Abkür-

zungen und andere Wortkürzungen verwenden, ausser sie sind in der projektspezifisch

zu erstellenden Liste der erlaubten Abkürzungen und Akronyme vorhanden.

MUST

NMR-086 Akronyme und Abkürzungen, die aufgelistet werden, MUESSEN immer anstelle der

ausgeschriebenen Wörter verwendet werden.

MUST

NMR-087 Akronyme MUESSEN immer komplett in Grossbuchstaben vorkommen, ausser das

Akronym steht am Anfang eines Attributnamen. In diesem Fall MUSS das Akronym in

Kleinbuchstaben geschrieben sein.

MUST



NMR-088 Ein XML Schema Namespace MUSS dem folgenden Pattern gehorchen:

URN urn:<organization>:<organization hierar-chy>[:<organization hierarchy level>]*:<schema type>[:<package>]+[:<status>]:v<major-version>

URL http://<organisation>/<organization hierar-chy>[/<organization hierarchy level>]*/<schema type>[/<package>]+[/<status>]/v<major-version>

wobei:

• organization – ein Identifier der Organisation, welche die Schemadefiniti-

on zur Verfügung stellt

• organization hierarchy – die erste Stufe einer Hierarchie innerhalb

der Organisation, welche die Schemadefinition zur Verfügung stellt

• organization hierarchy level – 0 oder mehrere Hierarchiestufen

der Organisation, welche die Schemadefinition zur Verfügung stellt

• schema type – ein Token, welcher den Typ des XML Schema Dokumentes

indentifiziert: schema | codelist | documentation

• package - eine oder mehrere Stufen von Packages getrennt durch ein „/”

Zeichen

• status – der optionale Status des WSDL-Dokumentes: draft | stan-

dard

• major – die Major Versionsnummer

Beispiele:

• http://trivadis.com/techdiv/schema/soabp/creditCard /v1

• http://trivadis.com/techdiv/codelist/soabp/common/I SOCountryList/v1

MUST



NMR-089 Die Filenamen von XML Schemas MUESSEN dem folgenden Pattern gehorchen:

<schema-module-name>_<major>.<minor>.xsd

sämtliche Punkten, Leerzeichen und andere Trennzeichen müssen entfernt werden.

wobei:

• Schema-module-name – Name des Schemamoduls

• major – Major-Versionsnummer

• minor – Minor Versionsummer

MUST

NMR-090 Das xsd:schema Versionsattribut MUSS dem folgenden Pattern gehorchen:

<xsd:schema ... version=“<major>.<minor>[.<revision >]”

wobei:

• <major> - sequentielle Nummer mit der Major-Version

• <minor> - sequentielle Nummer mit der Minor-Version

• <revision> - optionale, sequentielle Nummer mit der Revision-Nummer

MUST

6.1 Namens-Segmente in der Namensgebung von Element en, Typen und Attributen

Die Namen von Elementen, Attributen und Typen in einer Schemadefinition sollten sich wo möglich und sinnvoll aus einem projektspezifisch zu erstellenden Vokabular von standardi-sierten Begriffen zusammenzusetzen.

Falls vorhanden und möglich empfiehlt sich auch eine nahe Anlehnung von Komponenten-namen an die Namensgebung des zugrundeliegenden Objekt- oder Datenmodells.

6.1.1 Suffixe zur Bezeichnung des Datentyps

In der folgenden Tabelle sind im Sinne eines Beispiels und nicht abschliessend einige essen-tielle Begriffe aufgeführt, welche als Suffix in Komponentennamen verwendet werden sollten.

Bezeichner Beschreibung Primitive Datentypen

Amount Ein numerischer Wert, der einen monetären Wert darstellt. Die Währungseinheit kann dabei explizit oder implizit definiert sein.

Beispiele: UnitCostAmount , UnitPri-ceAmount, PartnerFeeAmount

• xsd:decimal

• xsd:double

• xsd:float

• xsd:integer

Binary Eine Sequenz von binären Ziffern um beispielswei-se Dokumente wie Word oder PDF einzubinden.

Beispiele: DocumentationBinary , Attach-mentBinary

• xsd:base64binary

• xsd:hexBinary



Code Ein Character String (Buchstaben, Zahlen oder Symbole) kann verwendet werden, um einen kürzeren oder sprach-unabhängiges Token zu haben, der einen Wert oder Text repräsentiert oder ersetzt. Codes werden normalerweise in Codelis-ten für jeden Attributtyp verwaltet.

Beispiele: CountryCode , CurrencyCode

• xsd:normalizedString

• xsd:string

• xsd:token

Date Ein Tag in einem bestimmten Kalenderjahr (ISO 8601-2000) als Darstellung im gregorianischen Kalender.

Beispiele: ExpirationDate , ShipmentDate

• xsd:date

DateTime Eine Kombination aus Datumsangeben des grego-rianischen Kalenders und Zeitangaben

Beispiele: CreationDateTime , ReceiptDa-teTime

• xsd:dateTime

Duration Eine Darstellung eines Zeitraumes in Jahren, Monaten, Wochen, Tagen, Stunden, Minuten, Sekunden und Sekundenbruchteilen im ISO 8601 Format.

Beispiele: ActivityDuration , WorkTimeDu-

ration

• xsd:duration

Identifier Ein Charakter String (Buchstaben, Zahlen oder Symbole) als eindeutiger Bezeichner einer Instanz eines Objektes.

Beispiele: CustomerIdentifier, OrderIden-tifier


• xsd:string

• xsd:token

Indicator Ein Bezeichner aus einer Liste von 2 sich gegen-seitig ausschliessenden Werten, welche den einzigen möglichen Zustand einer bestimmten Eigenschaft wiedergeben.

Beispiele: ActivationStatusIndicator, EligibilityIndicator

• xsd:boolean

Measure Ein numerischer Wert um physische Dimensionen eines Objektes zu beschreiben. Wird typischer-weise immer im Kontext einer Masseinheit ver-wendet.

Beispiele: WeightMeasure, LengthMeasure

• xsd:decimal

• xsd:double

• xsd:float

• xsd:integer

Name Die Benennung als Unterscheidungsmerkmal • xsd:normalizedString



eines bestimmten Objektes wie Person, Sache, Ort oder Konzept.

Beispiele: FirstName, LocationName

• xsd:string

• xsd:token

Ordinal Eine Zahl die einen mathematischen Wert darstellt, welche für Aufzählungen, Reihenfolgen und Sortie-rungen verwendet wird.

Beispiele: RankingOrdinal, OrderOrdinal

• xsd:integer

• xsd:positiveInteger

• xsd:nonNegativeInteger

• xsd:unsignedInt

• xsd:unsignedLong

Percent Ein Wert der eine Fraktion von hundert als Quoti-ent ausdrückt.

Beispiele: DiscountPercent, TaxPercent

• xsd:decimal

• xsd:double

• xsd:float

• xsd:integer

Quantity Ein numerischer Wert mit welchem eine Einheit von nicht monetären Werten ausgedrückt wird. Üblicherweise wird dieser Wert immer im Kontext einer Masseinheit ausgedrückt.

Beispiele: OrderQuantity, AvailableQuan-

tity

• xsd:decimal

• xsd:double

• xsd:float

• xsd:integer

Rate Eine Menge, Betrag, Häufigkeit oder Faktor, der gegen eine Basiseinheit gemessen und als Quoti-ent ausgedückt wird.

Beispiele: InterestRate, ConversionRate

• xsd:decimal

• xsd:double

• xsd:float

• xsd:integer

Ratio Eine Beziehung von zwei unabhängigen Mengen, welche die gleiche Masseinheit oder Währung verwenden. Ratio kann als Quotient oder Proporti-on ausgedrückt werden.

Beispiele: CompletionRatio, NetIncomeRa-tio

• xsd:decimal

• xsd:double

• xsd:float

• xsd:integer

Text Eine Charakter Zeichenkette in der Form einer Sprache welche zur unstrukturierten Beschreibung eines Objektes verwendet wird.

Beispiele: InvoiceText, RemarksText


• xsd:string

• xsd:token

Time Die Angabe einer Tageszeit im ISO 8601-2000 Format mit oder ohne Zeitzonenangabe, welche in Stunden, Minuten, Sekunden und Bruchteilen davon aufgelöst werden kann.

Beispiele: DeliveryTime, StartTime

• xsd:time

Value Ein numerischer Wert zur Darstellung von quantifi- • xsd:decimal



zierenden Informationen zu einer Objektinstant oder zur Darstellung von zugeordneten oder ge-planten Mengen.

Beispiele: TotalOrderValue, AssignedValue

• xsd:double

• xsd:float

• xsd:integer



6.1.2 Terminologie der Benennung von Businessobjekt en

Grundsätzlich sollte eine möglichst konsistente Terminologie der Bezeichnungen aus den jeweiligen Geschäftsfeldern oder der jeweiligen Branche verwendet werden. Die gleichbe-deutende Verwendung von verschiedenen Begriffen für dieselbe Entität oder Objekttyp sollte vermieden werden. Beispielsweise sollte nicht der Term „Supplier” und „Vendor” oder „CostCenter” und „BusinessUnit” gleichbedeutend für die Beschreibung des gleichen Entitätstyps eingesetzt werden. Zur verbesserten Übersichtlichkeit und intuitiven Benutzung der XML-Artefakte wird bei breiterer Verwendung von XML Schema, empfohlen ein Wörterbuch der zwingenden Begriffe für die Verwendung von Komponentennamen zu erstellen, welche bei der Namensgebung verbindlich zu verwenden sind. NMR-091 Bei umfangreicherer Anwendung von XML Schema SOLLTE ein anwendungsspezifisches

Dictionary von zwingend zu verwendenden Bezeichnungen der Geschäftsausdrücke als

Namenssegmente in Komponentennamen erstellt werden.

SHOULD



7 Links

7.1 XML-Spezifikationen

Die folgende Aufstellung zeigt die wichtigsten URIs der XML Spezifikation, welche in diesem Dokument referenziert werden

http://www.w3.org/TR/REC-xml/

Extensible Markup Language (XML) 1.0 (Fifth Edition) W3C Recommendation, 26. November 2008 XML 1.0

http://www.w3.org/TR/xml11/

Extensible Markup Language (XML) 1.1 (Second Edition) W3C Recommendation, 16 August 2006 XML 1.1

http://www.w3.org/TR/xmlschema-0

XML Schema Part 0: Primer Second Edition W3C Recommendation, 28 October 2004 XML Schema Facilities – XML 1.0


XML Schema Part 1: Structures Second Edition W3C Recommendation, 28 October 2004 XML Schema Structures – XML 1.0


XML Schema Part 2: Datatypes Second Edition W3C Recommendation, 28 October 2004 XML Schema Datatypes – XML 1.0

http://www.w3.org/TR/xml-names/

Namespaces in XML 1.0 (Third Edition) W3C Recommendation, 8 November 2009 XML 1.0

http://www.w3.org/TR/xml-names11/

Namespaces in XML 1.1 (Second Edition) W3C Recommendation, 16 August 2006 XML 1.1

http://www.w3.org/TR/xml-c14n/

Canonical XML – Version 1.0 W3C Recommendation, 15 March 2001 XML 1.0



7.2 Referenzen

[UN/CEFACT] United Nations Centre for Trade Facilitation and El ectronic Business UN/CEFACT Modelling Methodology (UMM) http://www.unece.org/cefact/xml/xml_index.htm

[REQ_COMM_2119] Key words for use in RFCs to Indicate Requirement Levels, March 1997, http://tools.ietf.org/html/rfc2119



8 Anhang A – Schema Beispiel

<?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSc hema" xmlns:adr="http://www.trivadis.com/samples/interna l/schema/Address/v1" xmlns:tns="http://www.trivadis.com/samples/interna l/schema/Person/v1" xmlns:can="http://www.trivadis.com/samples/schema/ common/CantonCodeEnum/v1" xmlns:com="http://www.trivadis.com/samples/schema/ common/CommonTypes/v1" xmlns:dse="http://www.trivadis.com/samples/schema/ common/DataStateEnum/v1" xmlns:rse="http://www.trivadis.com/samples/schema/ common/RecordStateEnum/v1" targetNamespace="http://www.trivadis.com/samples/i nternal/schema/Person/v1" elementFormDefault="qualified" attributeFormDefaul t="unqualified" finalDefault="#all" blockDefault="#all" version="1 .0"> <xsd:import namespace="http://www.trivadis.com/samp les/internal/schema/Address/v1" schemaLocation="../../common/Address/v1/Address-v1 .0.xsd"/> <xsd:import namespace="http://www.trivadis.com/samp les/schema/common/CantonCodeEnum/v1" schemaLocation="../../../../public/xsd/common/v1/ CantonCodeEnum-v1.0.xsd"/> <xsd:import namespace= http://www.trivadis.com/samples/schema/common/Commo nTypes/v1 schemaLocation="../../../../public/xsd/common/v1/C ommonTypes-v1.0.xsd"/> <xsd:import namespace= http://www.trivadis.com/samples/schema/common/DataS tateEnum/v1 schemaLocation="../../../../public/xsd/common/v1/D ataStateEnum-v1.0.xsd"/> <xsd:import namespace= http://www.trivadis.com/samples/schema/common/Recor dStateEnum/v1 schemaLocation="../../../../public/xsd/common/v1/R ecordStateEnum-v1.0.xsd"/> <xsd:simpleType name="AccountNumberType"> <xsd:restriction base="xsd:string"> <xsd:maxLength value="30"/> </xsd:restriction> </xsd:simpleType> <xsd:simpleType name="ClearingNumberType"> <xsd:restriction base="xsd:string"> <xsd:maxLength value="12"/> </xsd:restriction> </xsd:simpleType> <xsd:complexType name="PaymentInformationType"> <xsd:sequence> <xsd:element name="PaymentMethod" minOccurs="0" m axOccurs="1" type="tns:PaymentMethodEnumType"> <xsd:annotation> <xsd:documentation xml:lang="DE"> Zahlungsverfahren </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="ClearingNumber" minOccurs="1" maxOccurs="1" type="tns:ClearingNumberType"> </xsd:element> <xsd:element name="BankAccountNumber" minOccurs=" 0" maxOccurs="1" type="tns:AccountNumberType"> </xsd:element> <xsd:element name="PostAccountNumber" minOccurs=" 0" maxOccurs="1" type="tns:AccountNumberType"> </xsd:element> <xsd:element name="Recipient" minOccurs="1" maxOc curs="1" type="com:PersonNameType"> </xsd:element> <xsd:element name="FirstName" minOccurs="0" maxOc curs="1" type="com:PersonNameType"> </xsd:element> <xsd:element name="LastName" minOccurs="0" maxOcc urs="1" type="com:PersonNameType"> </xsd:element> <xsd:element name="Iban" minOccurs="0" maxOccurs= "1" type="com:Max30TextType">



</xsd:element> <xsd:element name="Swift" minOccurs="0" maxOccurs ="1" type="com:Max12TextType"> </xsd:element> <xsd:element name="EBillingEnabled" minOccurs="0" maxOccurs="1" type="xsd:boolean"> </xsd:element> <xsd:element name="EBillingAccountNumber" minOccu rs="0" maxOccurs="1" type="com:Max30TextType"> </xsd:element> </xsd:sequence> </xsd:complexType> <xsd:simpleType name="PaymentMethodEnumType"> <xsd:restriction base="xsd:string"> <xsd:enumeration value="00"/> <xsd:enumeration value="01"/> <xsd:enumeration value="51"/> <xsd:enumeration value="52"/> </xsd:restriction> </xsd:simpleType> <xsd:complexType name="PersonType"> <xsd:sequence> <xsd:element name="PersonPin" minOccurs="0" maxOc curs="1" type="com:PersonPinType"> </xsd:element> <xsd:element ref="com:CantonRecordData" minOccurs ="1" maxOccurs="1"/> <xsd:element name="RecordState" minOccurs="1" max Occurs="1" type="rse:RecordStateEnumType"> </xsd:element> <xsd:element name="OrganisationName" minOccurs="0 " maxOccurs="1" type="com:Max50TextType"> </xsd:element> <xsd:element name="OrganisationAdditionalName" mi nOccurs="0" maxOccurs="1" type="com:Max50TextType"/> <xsd:element name="Department" minOccurs="0" maxO ccurs="1" type="com:Max50TextType"> </xsd:element> <xsd:element name="OfficialName" minOccurs="0" ma xOccurs="1" type="com:PersonNameType"> </xsd:element> <xsd:element name="OriginalName" minOccurs="0" ma xOccurs="1" type="com:PersonNameType"> </xsd:element> <xsd:element name="FirstName" minOccurs="0" maxOc curs="1" type="com:PersonNameType"> </xsd:element> <xsd:element name="DateOfBirth" minOccurs="0" max Occurs="1" type="xsd:date"> </xsd:element> <xsd:element name="PlaceOfOrigins" minOccurs="0" maxOccurs="1"> <xsd:complexType> <xsd:sequence> <xsd:element ref="com:PlaceOfOrigin" minOccurs ="1" maxOccurs="2"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="PlaceOfBirthCountry" minOccurs ="0" maxOccurs="1" type="com:Max30TextType"/> <xsd:element name="Sex" minOccurs="0" maxOccurs=" 1" type="com:GenderEnumType"> </xsd:element> <xsd:element name="Language" minOccurs="0" maxOcc urs="1" type="com:Max1TextType"> </xsd:element> <xsd:element name="Nationality" minOccurs="1" max Occurs="1" type="com:CountryType"> </xsd:element>



<xsd:element name="CantonOfOrigin" minOccurs="0" maxOccurs="1" type="can:CantonCodeEnumType"> </xsd:element> <xsd:element name="CountryOfOrigin" minOccurs="0" maxOccurs="1" type="com:CountryType"> </xsd:element> <xsd:element name="Remark" minOccurs="0" maxOccur s="1" type="com:Max50TextType"> </xsd:element> <xsd:element name="Phone" minOccurs="0" maxOccurs ="1" type="com:Max30TextType"> </xsd:element> <xsd:element name="Cell" minOccurs="0" maxOccurs= "1" type="com:Max30TextType"> </xsd:element> <xsd:element name="Email" minOccurs="0" maxOccurs ="1" type="com:Max50TextType"> </xsd:element> <xsd:element name="PaymentInformation" minOccurs= "0" maxOccurs="1" type="tns:PaymentInformationType"> </xsd:element> <xsd:element name="Archived" minOccurs="0" maxOcc urs="1" type="xsd:boolean"> </xsd:element> <xsd:element ref="com:BaseAudit" minOccurs="0" ma xOccurs="1"/> </xsd:sequence> </xsd:complexType> <xsd:element name="Person" type="tns:PersonType"/> <xsd:element name="PaymentInformation" type="tns:Pa ymentInformationType"/> </xsd:schema>

xml schema design - trivadis.com · soa guidelines – xml schema design version 1.0 seite 2/46...

Documents