Dieses Handbuch soll Herausgeber und Nutzer von Codelisten unterstützen. Bei der Herausgabe und Nutzung von Codelisten sind häufig Interaktionen mit einer ganzen Reihe von Beteiligten erforderlich. Die jeweils an diesen Interaktionen beteiligten Organisationen und Personen haben dabei sehr unterschiedlich, durch ihre Rollen, Teilaufgaben und Anforderungen geprägte Perspektiven auf das Thema.

Mit diesem Handbuch wird eine übergreifende Perspektive dargestellt, die allen Beteiligten ein einheitliches Vokabular und Regelwerk unter anderem in Form eines Standards zur Herausgabe und Nutzung von Codelisten an die Hand gibt. Eine solches einheitliches Vokabular und Regelwerk wird als notwendige Grundlage für eine transparente, qualitätsgesicherte und letztendlich effiziente Herausgabe und Nutzung von Codelisten verstanden.

Zielgruppe dieses Dokuments sind Organisationen und Personen, die an der Herausgabe und Nutzung beteiligt sind. Im Kontext dieses Handbuchs umfasst der Gesamtprozess der Herausgabe einer Codeliste und ihrer Versionen die folgenden Teilprozesse:

Die Nutzung von Codelisten und zugehörigen Versionen soll u. a. verstanden werden als Nutzung in den folgenden Kontexten:

Weitere Nutzungskontexte sind in diesem Zusammenhang vorstellbar, sollen aber im Weiteren nicht explizit dargestellt werden.

Zielgruppe dieses Dokuments sind somit neben Anderen die folgenden Organisationen

In diesem Zusammenhang sollen insbesondere die Mitarbeitenden der oben genannten Organisationen angesprochen werden, die in den Rollen Fachexperte, Fachlicher Entscheider, IT-Architekt und IT-Entwickler agieren.

Das vorliegende Codelisten-Handbuch und der darin spezifizierte Standard ist ein durch die Koordinierungsstelle für IT-Standards (KoSIT) im Auftrag des IT-Planungsrats betriebenes und unter der CC BY Lizenz (Creative Commons Namensnennung 4.0) verfügbares Produkt. Handbuch und Standard unterliegen dem geregelten Produktbetrieb. Änderungsanforderungen, Erweiterungen oder Fehlermeldungen können durch alle Nutzer an die KoSIT (kosit@finanzen.bremen.de) gemeldet werden.

An der vorliegenden Fassung des Handbuchs haben folgende Personen mitgewirkt:

Dieses Handbuch ist in drei Abschnitte gegliedert. Das Standard zur Herausgabe und Nutzung von Codelisten bildet den normativen Teil dieses Dokuments. Es definiert welche Daten und Metadaten eine Codeliste enthält, wie sie und ihre Versionen zu identifizieren sind und welche Konformitätskriterien gelten. Der Leitfaden zur Bereitstellung und Einbindung von Codelisten (nicht normativ) bietet einen Leitfaden zur strukturierten und vorhabenübergreifenden Nutzung von Codelisten. Es werden die Bereitstellung von Codelisten im XRepository sowie die verschiedenen Methoden der Einbindung von Codelisten in das eigene Vorhaben erläutert. Das Kapitel Abbildung von Codelisten in technische Formate spezifiziert die Abbildung von Codelisten im Sinne dieses Standards aus technischer Sicht. Es werden Syntaxbindings für Genericode und XÖV-Fachmodelle erläutert und an Beispielen veranschaulicht. Im Anhang Übersicht Syntaxbinding findet sich eine tabellarische Übersicht dieser Abbildungen. Den Abschluss bildet das Glossar.

Eine Codeliste wird im Kontext dieses Handbuchs definiert als eine Liste von Codes und zugehöriger Beschreibung(en). Codes und zugehörige Beschreibungen können, wie im Folgenden illustriert, als Tabelle dargestellt werden. Die Tabelle zeigt beispielhaft die Daten einer Codeliste zur Übermittlung des Familienstands, wie sie in vergleichbarer Form im Standard XMeld verwendet wird.

Die Codeliste enthält insgesamt zehn Einträge, die den Tabellenzeilen in der Darstellung entsprechen. Die Benennung der (Tabellen-)Spalten kann frei gewählt werden. In der Spalte “SpalteA” sind die Codes der Einträge abgebildet, die innerhalb der Codeliste eindeutig sein müssen. Diese Spalte wird im Weiteren als Codespalte bezeichnet. In der Spalte “SpalteB” ist die Bedeutung der jeweiligen Codes beschrieben.

Komplexere Sachverhalte können es erfordern, dass wie in der folgenden Tabelle dargestellt, mehr als eine Code-Spalte und/oder eine Beschreibungsspalte erforderlich sind. Das Beispiel zeigt ausschnittweise sieben Einträge der von der KoSIT herausgegebenen und im XRepository veröffentlichten Codeliste “Country Codes”.

Für diese Codeliste sind mit den Spalten “ISO Alpha-2 code” und “ISO Numeric” insgesamt zwei Codespalten definiert. Mit den Spalten “DESTATIS Code”, “Short Name” und “Full Name” sind insgesamt drei Beschreibungsspalten gegeben. Eine solche "Mehrfachauszeichnung" der Einträge kann u. a. für Codelisten hilfreich sein, die in unterschiedlichen Bereichen genutzt werden sollen, in denen sich unterschiedliche Begrifflichkeiten oder Codes für die selben semantischen Konzepte etabliert haben. Die in der o. g. Liste aufgeführten Staaten können entweder mittels ISO Alpha-2 code (z. B. DE) oder ISO Numeric (z. B. 276) identifiziert werden.

In bestimmten Anwendungskontexten kann es notwendig sein, Daten und Metadaten in mehreren Sprachen anzugeben. Die vorliegende Methodik ermöglicht die Anlage und Nutzung solcher Codelisten durch Verwendung entsprechender Metadaten, wie sie im folgenden Metadaten einer Codeliste beschrieben sind.

Das folgende Beispiel greift die bereits erwähnte Familienstands-Codeliste - ergänzt um eine weitere englischsprachige Kommentarspalte - wieder auf. In den Spaltenmetadaten (hier und im Folgenden dargestellt als Tabellenkopf) wird die Sprache der zugehörigen Daten ausgezeichnet.

Die im folgenden Abschnitt Metadaten einer Codeliste als "mehrsprachig" gekennzeichneten Elemente können in verschiedenen Sprachen angegeben werden. So kann beispielsweise der Name (lang) einer Codeliste sowohl auf Englisch als auch auf Deutsch angegeben werden (nicht aber die notwendig eindeutige Kennung der Codeliste).

Wird ein Metadatum in einer Sprache verwendet, muss es auch in jeder anderen der verwendeten Sprachen aufgeführt werden (der Name der Codeliste muss beispielsweise in jeder verwendeten Sprache genau einmal vorkommen).

Dabei muss die Sprache im Format des RFC 5646 spezifiziert werden (ISO 639-1 zur Angabe von Sprachen, ISO 3166-1 zur Angabe des Landes); also z. B. „de-DE“ für das in Deutschland geschriebene Deutsch, „en-US“ für amerikanisches Englisch, etc.

Die Verwendung von Sprachen im Daten- und im Metadatenteil der Codeliste ist unabhängig voneinander: Es können Daten (Tabellenspalten) in mehreren Sprachen und gleichzeitig Metadaten in nur in einer Sprache vorliegen - oder umgekehrt.

Um den Umgang mit Codelisten im Kontext der deutschen Verwaltung zu erleichtern, muss jede Codeliste mindestens deutschsprachige (de-DE) Metadaten enthalten. Wird eine Codeliste ausschließlich im in Deutschland geschriebenem Deutsch (de-DE) verfasst, kann auf die sprachliche Auszeichnung der Metadaten und Spalten verzichtet werden.

Eine tabellarische Aufstellung der Regelungen findet sich unter Regelungen zu Codelisten.

Neben den Daten ("Einträge der Tabelle") einer Codeliste erfordert deren systematische Nutzung die Beschreibung der Codeliste als solche, ihrer Versionen und der zugehörigen Daten. Diese sogenannten Metadaten informieren unter anderem über Name, Version, Gültigkeit und Herausgeber einer Codeliste. Im Folgenden wird unterschieden in Metadaten, die

beschreiben. Die unten stehenden Tabellen bieten einen Überblick über eine Mindestmenge von Metadaten der drei Kategorien. Die Mindestmenge ist die Menge von (Meta-)Daten, die unabhängig von spezifischen Herausgabe- oder Nutzungskontexten allen Beteiligten in definierter Form und Qualität verlässlich zur Verfügung stehen muss.

Die in den Tabellen spezifizierten Metadatenelemente sind normativer Bestandteil des Standards und somit relevant für die Beurteilung der Konformität einer Codeliste zum Codelisten-Handbuch (semantischen Standard).

Metadaten die im Folgenden als mehrsprachig gekennzeichnet sind, können parallel in mehreren Sprachen angegeben werden. Sobald ein Metadatenelement in einer Sprache angegeben wird, muss es in alle verwendeten Sprachen übersetzt werden. Beispiel: Die verpflichtenden Metadatenelemente (Häufigkeit: 1) sind auf Deutsch angegeben. Wird nun eins der Elemente auf Englisch übersetzt, so müssen auch alle anderen als mehrsprachig gekennzeichneten Elemente in einer englischsprachigen Übersetzung vorliegen. Wird darüber hinaus ein optionales Element (Häufigkeit: 0..1 oder 0..*) verwendet, so muss auch dies übersetzt werden.

Eine Codeliste kann 0..n Versionen besitzen. Die Metadatenelemente zur Beschreibung einer solchen Codelistenversion sind mit der folgenden Tabelle gegeben.

Eine Codeliste besitzt mindestens eine Spalte zur Abbildung ihrer Codes und mindestens eine Spalte zur Abbildung der Beschreibung des jeweiligen Codes. Jede Spalte einer Codeliste muss über die im Folgenden gegebenen Metadatenelemente die in ihr gehaltenen Daten spezifizieren.

Darüber hinaus kann jeder Spalte per Metadatum "Sprache" optional eine Sprache / Länderkontext zugewiesen werden (Metadatum "Sprache"). Die Metadaten der Spalte selbst sind in der mit dem Metadatum "Sprache" für die Spalte angegebenen Sprache anzugeben.

Eine mehrsprachige Angabe der Spaltenmetadaten selbst (z. B. eine deutsche Übersetzung des Spaltennamens einer englischsprachigen Spalte) ist nicht vorgesehen.

Neben der in den Tabellen aufgeführten Mindestmenge an zu verwendenden Metadatenelementen können weitere Daten zur Beschreibung von Codelisten und Versionen in spezifischen Kontexten erforderlich oder hilfreich sein. Wird beispielsweise eine Codeliste über die Plattform XRepository bereitgestellt, werden weitere Metadaten zum Status der Codeliste, dem Einstelldatum oder dem Datum ihrer letzten Bearbeitung im XRepository geführt.

Die eindeutige und bereichsübergreifende Identifikation von Codelisten und deren Versionen ist eine zwingende Voraussetzung für eine qualitätsgesicherte und transparente Herausgabe und Nutzung. Zur Identifikation werden Kennungen genutzt. Die folgenden Regelungen zur Bildung von Kennungen sind die Grundlage für ein einheitliches Verständnis von Herausgeber und Nutzer und unterstützen die gemeinschaftliche Verwendung von Codelisten.

Die Kennung von Codelisten und Codelistenversionen muss in der URN-Syntax gebildet werden. Die allgemeine URN-Syntax ist mit "RFC8141" der Internet Engineering Task Force (IETF) vorgegeben.^[3] Mit der URN-Syntax soll die globale Eindeutigkeit von Kennungen sichergestellt werden. Hierzu ist der URN in einen globalen und einen lokalen Teil unterteilt. Der globale Teil stellt die globale Eindeutigkeit sicher und verweist auf einen Namensraum mit einer spezifischen Syntax, die die Bildung des lokalen Teils regelt und somit die lokale Eindeutigkeit sicherstellt. Die KoSIT bietet zur Bildung von Kennungen für Standards und Codelisten den globalen Teil urn:xoev-de: und eine zugehörige Syntax zur Bildung des lokalen Teils an. Die Verwendung des globalen Teils ist für Standards, XÖV-Kernkomponenten und XÖV-Datentypen und deren Versionen verpflichtend und wird für Codelisten und Versionen empfohlen. Mit der Verwendung des globalen Teils ist die Verwendung der im Folgenden beschriebenen, zugehörigen Syntax obligatorisch.

Die Kennung einer Codeliste, die den globalen Teil urn:xoev-de: verwendet, ist wie folgt aufgebaut:

Die kursiv dargestellten Bestandteile der Kennung sind vom Herausgeber des Inhalts nach den folgenden Regelungen auszugestalten.

Die Kennung einer Version einer Codeliste wird, wie im Folgenden dargestellt, gebildet aus der Kennung des zugehörigen Inhalts, dem verbindenden Zeichen _ und der Versionsangabe.

Zur Illustration der oben dargestellten Regelungen ist im Folgenden beispielhaft die Versionskennung der durch die KoSIT im XRepository herausgegebenen Codeliste "Country Codes" in der Version "2" dargestellt.

Die folgenden Konformitätskriterien sind wie auch die unter Metadaten einer Codeliste dargestellten Metadatenelemente normativer Bestandteil des hier beschriebenen Standards. Sie bilden die messbare Grundlage für die Feststellung der Konformität einer Codeliste zum vorliegenden Codelisten-Handbuch bzw. zum darin dargestellten semantischen Datenmodell.

Es werden die Verbindlichkeitsstufen MUSS und SOLL unterschieden.

Die Nutzung der durch die KoSIT bereitgestellten Produkte stellt, sofern technisch möglich, die Einhaltung der MUSS- und SOLL-Regeln sicher und unterstützt so Herausgeber in der Ausgestaltung und technischen Abbildung seiner Codeliste.

Die Inhalte des Abschnitts sind nicht normativ. Sie sollen den Beteiligten als Leitfaden und Entscheidungshilfe bei der Ausgestaltung der Prozesse der Herausgabe und Nutzung von Codelisten dienen.

Die öffentliche Bereitstellung von Codelisten und zugehörigen Metadaten ist grundlegende Voraussetzung der gemeinsamen, standardübergreifenden Nutzung von Codelisten. Die einheitliche Verwendung von Metadaten und Daten-Formaten unterstützt darüber hinaus die effiziente Umsetzung eines Standards in IT-Verfahren. Mit dem XRepository wird durch die KoSIT im Auftrag des IT-Planungsrats eine Infrastrukturkomponente für Herausgeber und Nutzer von Codelisten und (XÖV-)Standards betrieben, die durch alle Beteiligten zur zentralen Bereitstellung und zum Bezug kostenfrei genutzt werden kann.

Die Verwendung des XRepository ist für die unterschiedlichen Beteiligten rund um die Herausgabe und Nutzung von Codelisten u. a. aus den folgenden Gründen nützlich:

Die Inhalte des Abschnitts sind nicht normativ. Sie sollen den Beteiligten als Leitfaden und Entscheidungshilfe bei der konkreten Ausgestaltung der Nutzung von Codelisten dienen.

An die Nutzung von Codelisten werden aus der Praxis vielfältige, sich zum Teil widersprechende Anforderungen gestellt. In der Fragestellung wie die konkrete Nutzung einer Codeliste im praktischen Anwendungsfall erfolgen soll, spielen unterschiedlichste Kriterien eine Rolle.

Im Folgenden sollen einige der Kriterien aufgelistet werden, die in der Praxis die letztendliche Art der Nutzung einer Codeliste entscheidend beeinflussen können und anhand von bekannten Nutzungskontexten illustriert werden.

Auf der Basis o. g. und weiterer Kriterien können die spezifischen Anforderungen an die umzusetzende Codelistennutzung konkretisiert und die Entscheidung für eine bestimmte Ausgestaltung der Nutzung herbeigeführt werden.

Im Folgenden sind zur Verdeutlichung möglicher Ausgestaltungen vier grundlegende Typen der Nutzung einer Codeliste durch einen Standard dargestellt. Mit entsprechenden Einschränkungen können diese Nutzungstypen auch auf andere Szenarien wie beispielsweise der Nutzung einer Codeliste durch ein IT-Verfahren übertragen werden.

Charakteristisch für die jeweiligen Typen ist der Zeitpunkt, zu dem die Festlegung der konkret zu nutzenden Codelistenversion bestimmt wird und ob die Metadaten und Daten der Codeliste in die technischen Bestandteile des Standards übernommen werden sollen.

Der OASIS-Standard^[5] Genericode ermöglicht die Abbildung von Codelisteninhalten und zugehörigen Metadaten in XML-Instanzen. Zur Abbildung der im XÖV-Kontext erforderlichen Informationen wurden die im Genericode-Standard vorgesehenen Metadaten um entsprechende XÖV-Metadaten mit dem Namensraum http://xoev.de/schemata/genericode/4 (Präfix xoev-cl-4) ergänzt.

Im Folgenden ist dokumentiert, wie Metadaten im Genericode-Format abgebildet werden. Dazu sind die Bestandteile des konzeptionellen Modells den jeweiligen XML-Elementen bzw. -Attributen gegenübergestellt. Der darauffolgende Beispiele illustriert das Vorgehen.

Für Metadatenelemente die als "mehrsprachig" gekennzeichnet sind ist die angegebene Häufigkeit bzgl. jeder verwendeten Sprache zu beachten. Die Sprachangaben erfolgen auf Ebenen der Codelisten- und Versionsmetadaten mit dem Attribut xml:lang aus dem XML-Namensraum. Auf Ebene der Daten wird die Sprache pro Spalte über das Metadatum "Sprache" angegeben.

Eine Codeliste wird als UML-Klasse modelliert, die mit dem Stereotyp xoevCodeliste annotiert ist. Über die Eigenschaften des Stereotyps werden alle Metadaten der Codeliste dokumentiert, die sich mittels des für XÖV erweiterten Genericode-Standards abbilden lassen (siehe auch Metadatenelemente einer Codeliste (versionsunabhängig)).

Zu einer Codeliste zugehörige Versionen werden als UML-Klassen modelliert, die eine UML-Abhängigkeitsbeziehung zu der Codeliste besitzen. Über die Eigenschaften des Stereotyps xoevVersionCodeliste werden alle Metadaten der Codelistenversion dokumentiert, die sich mittels des für XÖV erweiterten Genericode-Standards abbilden lassen (siehe auch Metadatenelemente einer Codelistenversion (versionsabhängig)).

Die einzelnen Spalten einer Codelistenversion werden als UML-Eigenschaften modelliert, die mit dem Stereotyp xoevCodelistenspalte annotiert sind. Über die Eigenschaften des Stereotyps werden die Metadaten einer Codelistenspalte dokumentiert (siehe auch Metadatenelemente zur Strukturierung von Codelistendaten). Der Name der Eigenschaft stellt den “Spaltennamen (technisch)” dar.

Das Dokument wurde nach asciidoc überführt. Kleinere Strukturänderungen wurden vorgenommen.

Abschnitt 1.2: Korrektur eines Tippfehlers.

Abschnitt 1.3: Korrektur eines Tippfehlers.

Abschnitt 3.1: Korrektur eines Tippfehlers: Es wurde fälschlich der Namensraum http://xoev.de/schemata/genericode/3 statt http://xoev.de/schemata/genericode/4 benannt.

Appendix D: Eintrag zum XÖV-Primer in das Glossar eingefügt. Hinweis auf erfolgte Abschaltung des Genericoders.

Abschnitt 1.2: Neuer Abschnitt zu mehrsprachigen Codelisten.

Abschnitt 1.3: Hinweise zur Verwendung der Metadaten in mehrsprachigen Codelisten wurden ergänzt.

Abschnitt 1.5: Regelungen bezüglich mehrsprachigen Codelisten wurden hinzugefügt (K-10 bis K-13).

Kapitel 3: Übersichten wurden um mehrsprachige Elemente ergänzt. Das Element "xml:lang" wurde aus der Liste der nicht zu nutzenden Genericode-Elemente entfernt. Die Beispiele (3.1.2) wurden um Mehrsprachigkeit ergänzt.

Abschnitt 3.2: Bisheriger Abschnitt 3.2 (Intermediärformat Microsoft Excel) entfällt. Ehemals Abschnitt 3.3: Der Abschnitt 3.2.3 “Modellierung mehrsprachiger Codelisten” wurde ergänzt.

Appendix A: Die Übersicht über das Syntax-Binding wurde um Angaben zur Mehrsprachigkeit ergänzt. Das Binding für MS Excel wurde entfernt.

Anhang D. Glossar: Begrifflichkeiten aus dem Bereich mehrsprachige Codelisten ergänzt. Hinweis auf Abschaltung des Genericoders eingefügt.

Abschnitt 1.2: Multiplizität des Codelisten-Metadatums Herausgebername (kurz) von 0..1 zu 1 geändert. (Issue 9)

Abschnitt 3.1: Der einleitende Absatz wurde um Hinweise zu den ergänzten XÖV-spezifischen Metadaten-Elementen erweitert. (Issue 23)

Abschnitt 3.1.1: Der einleitende Absatz wurde redaktionell überarbeitet. (Issue 7)

Initiale Erstellung der Codelisten-Handbuchs.