EDM Webservice für die Codelisten-Abfrage v1.01

Anhang zur Schnittstellenbeschreibung

BMK_Logo_srgb

Bundesministerium für Klimaschutz, Umwelt, Energie, Mobilität, Innovation und Technologie (BMK)

Stubenbastei 5, 1010 Wien

edm-logo


Inhaltsverzeichnis

Einleitung

Schnittstellenbeschreibung

Genericode-Format-Beschreibung

Dateien und Ordner im Spezifikationspaket

Dateien und Ordner

Erläuterungen

Webservice-Operationen (aus codelist_webservice.wsdl)

Inputs und Outputs der Webservice-Operationen (aus codelist_webservice_types.xsd)

Message-Formate (aus genericode_excerpt.xsd)

Spezifikations-Änderungsverzeichnis

Änderungsverzeichnis

Einleitung

Disclaimer

	CODELIST v1.01

	Copyright (C) 2023 Environment Agency Austria
	Contact: edm-helpdesk@umweltbundesamt.at

	Commissioned by the Austrian Federal Ministry of Environment (BMK)

	Licensed under the EUPL, Version 1.2 or – as soon they will be approved
	by the European Commission – subsequent versions of the EUPL (the "Licence");

	You may not use this work except in compliance with the Licence.

	You may obtain a copy of the Licence at: http://joinup.ec.europa.eu/software/page/eupl

	Unless required by applicable law or agreed to in writing, work distributed under the licence is distributed
	on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

	See the Licence for the specific language governing permissions and limitations under the Licence.

Schnittstellenbeschreibung

In dieser Version des Spezifikationspakets besteht die Schnittstellenbeschreibung aus zwei Teilen:

  1. Hauptteil im PDF-Format
  2. Dieser Anhang im HTML-Format

Der Hauptteil im PDF-Format enthält Hintergrundinformationen, sowie Informationen zu zahlreichen Details, etwa zur Webservice-Authentifizierung.

Dieser Anhang im HTML-Format enthält eine detaillierte Beschreibung der Webservice-Operationen mit ihren Inputs und Outputs. Die Autoren der Spezifikation haben den Großteil der Inhalte dieses Anhangs im HTML-Format automatisiert erstellt, z.B. aus den annotierten im Spezifikationspaket enthaltenen WSDL- und XSD-Dateien. Annotierte WSDL- und XSD-Dateien enthalten Beschreibungstexte zu Webservice-Operationen bzw. zu Datenelementen.

Genericode-Format-Beschreibung

Dieses HTML-Beschreibung enthält im Abschnitt Message-Formate (aus genericode_excerpt.xsd) eine Beschreibung des verwendeten standardisierten Genericode-XML-Formats.

Für das verwendete Genericode-XML-Format und dessen Beschreibung gilt, dass das Spezifikationspaket nicht die originale Genericode-XSD-Datei enthält, sondern auf Basis der originalen Genericode-XSD-Datei generierte Dateien, auf die folgendes zutrifft:

  1. Sie enthalten nur jene Inhalte aus dem Genericode-Standard, welche das Webservice für die Codelisten-Abfrage tatsächlich verwendet
  2. Sie enthalten vereinfachte Definitionen, die exakt den Definitionen aus dem Genericode-Standard entsprechen. Die Vereinfachungen bestehen beispielsweise aus dem "Auflösen" von Gruppen. Die Vereinfachungen erleichtern das Lesen und Verwenden der Genericode-XSD-Dateien

Dateien und Ordner im Spezifikationspaket

Dateien und Ordner

NameSizeModified
xml_example_msg—
xml_example_service_input_output—
z_descr_img—
codelist_doc.pdf884 KB
codelist_doc_annex.html109 KB
codelist_webservice.wsdl4 KB
codelist_webservice_annot.wsdl9 KB
codelist_webservice_types.xsd3 KB
codelist_webservice_types_annot.xsd15 KB
genericode_excerpt.xsd7 KB
genericode_excerpt_annot.xsd18 KB

Erläuterungen

xml_example_msg/

Enthält Beispiele für edm.gv.at Codelisten und Relationen im Genericode-Format.

Das EDM Webservice für die Codelisten-Abfrage liefert abgefragte Codelisten und Relationen in genau diesem Format.

xml_example_service_input_output/

Enthält für jede Operation des Codelisten Webservice genau einen Beispiel-Input und Beispiel-Output. Enthält zudem einen Beispiel-[SOAP]-Fault.

z_descr_img/

Für die Ordner, deren Namen mit "z_" beginnt, ist es für gewöhnlich nicht sinnvoll, diese einzeln durchzusehen. Vielmehr verlinkt die Beschreibung auf Inhalte dieser Ordner.

Der Ordner z_descr_img enthält die in der Beschreibung EDM_CodelistenWebservice_Beschreibung_Anhang.html verwendeten Bilddateien.

codelist_doc.pdf

Die Anleitung zur korrekten Verwendung des Datenformats bzw. der Schnittstelle.

codelist_doc_annex.html

Anhang zur Schnittstellenbeschreibung. Beschreibt insbesondere die Webservice-Operationen mit deren Inputs und Outputs im Detail. Die Spezifikationsautoren haben einen Großteil des Inhalts dieses Anhangs automatisiert generiert, z.B. aus annotierten XSD-Dateien.

codelist_webservice_types.xsd; codelist_webservice_types_annot.xsd

Definiert die XML-Formate für die Inputs und Outputs der Codelisten Webservice Operationen in der formalen Sprache XSD. Besitzt eine direkte Abhängigkeit zu genericode_excerpt.xsd.

Eine Gültigkeit von Operations-Inputs bezüglich der in codelist_webservice_types.xsd definierten XML-Formate ist technische Voraussetzung dafür, dass das Codelisten Webservice eine Webservice-Interaktion erfolgreich abarbeiten kann.

Umgekehrt kann sich an das Codelisten Webservice angebundene Software darauf verlassen (bzw. dies auch validieren), dass Operations-Outputs des Webservice gültig bezüglich der in codelist_webservice_types.xsd definierten Operations-Output-XML-Formate ist.

codelist_webservice.wsdl; codelist_webservice_annot.wsdl

Beschreibt die Operationen des Codelisten Abfrage Webservice und deren Inputs und Outputs in der formalen Sprache [WSDL]. Nutzt codelist_webservice_types.xsd direkt, und somit genericode_excerpt.xsd indirekt.

Kann beispielsweise mit [SOAP]-Werkzeugen wie [SoapUI] genutzt werden, um automatisiert Webservice-Interaktionen für alle Operationen des Webservice zu generieren.

genericode_excerpt.xsd; genericode_excerpt_annot.xsd

Auszug aus der zum Genericode-Standard gehörenden Spezifikation des Genericode-XML-Formats in der formalen Sprache XSD.

Anmerkung: Die Autoren der Spezifikation haben die im Spezifikationspaket enthaltenen Genericode-XSD-Dateien aus den originalen zum Genericode gehörenden XSD-Dateien automatisiert generiert bzw. abgeleitet. Diese Ableitung/Aufbereitung hat den folgenden Zweck:

    1. Vereinfachung für die Nutzung und das Lesen der XSD-Dateien - Verwendung eines kleineren XSD-Sprachumfangs zur Definition der XML-Strukturen, z.B. "Auflösen" von group-Definitionen; auch als Basis für die im Abschnitt Message-Formate (aus genericode_excerpt.xsd) bereitgestellte automatisiert aus genericode_excerpt_annot.xsd generierte Beschreibung der aus dem Genericode-Standard im Webservice verwendeten XML-Strukturen
    2. Weglassen von in dieser Spezifikation bzw. Schnittstelle nicht genutzten Teilen der Original-Genericode-XSDs

Webservice-Operationen (aus codelist_webservice.wsdl)

Inhalt

Beschreibung der mit der Datei ↗codelist_webservice.wsdl definierten Webservice-Operationen. codelist_webservice.wsdl beschreibt die Webservice-Operationen mit der standardisierten formalen Sprache ↗Web Services Description Language (WSDL) 2.0.

Die vorliegenden Beschreibung ist automatisiert aus der annotierten WSDL-Datei ↗codelist_webservice_annot.wsdl generiert. Es ist daher möglich, alternativ zu dieser Beschreibung direkt die annotierte WSDL-Datei zu verwenden.

Verzeichnis

Operationen

GetCodeListByID

GetMappingByID

GetLatestChangeDates

Operationen

GetCodeListByID

Die Operation liefert die Einträge einer Codeliste.

Anmerkung: Die Operation liefert die Einträge mit Informationen zu deren Gültigkeit (Gültigkeitsbeginn, Gültigkeitsende), und liefert die Liste mit der gesamten Historie aller Einträge, inklusive zum Abfragezeitpunkt nicht mehr gültiger oder noch nicht gültiger Einträge.

Port-Typ

CodeListPortType

Input

🠖cls:GetCodeListByIDRequest

Der Operations-Input besteht aus zwei Abfragekriterien, zum Einen der 4-stelligen Nummer der vom Webservice auszuliefernden Codeliste, und zum Anderen dem Code der Sprache, in welcher das Webservice die Codeliste ausliefern soll.

Anmerkung: Für alle in edm.gv.at verwalteten Codelisten stehen deutschsprachige Inhalte zur Verfügung (Sprachcode »de«). Für einzelne der in edm.gv.at verwalteten Codelisten, z.B. die in Zusammenhang mit Abfallverbringungen genutzten Codelisten, stehen zusätzlich englischsprachige Inhalte zur Verfügung (Sprachcode »en«).

Output

🠖cls:GetCodeListByIDResponse

Der Operations-Output besteht aus den Einträgen der abgefragten Codeliste.

Anmerkung: Die Operation liefert die Codelisten-Inhalte im standardisierten Genericode-XML-Datenformat, http://docs.oasis-open.org/codelist/cs-genericode-1.0/doc/oasis-code-list-representation-genericode.html.

Fault

🠖cls:Failure

Wenn bei der Verarbeitung des GetCodeListByID-Aufrufs ein Fehler auftritt, dann reagiert das Webservice mit einem SOAP 1.1 Fault. Das Webservice kann eines oder mehrere der folgenden in SOAP 1.1 definierten Fault-Elemente zur näheren Beschreibung des Fehlers nutzen:

  • faultcode
  • faultstring
  • detail mit Failure-Element-Inhalt

GetMappingByID

Die Operation liefert die Einträge einer Relation.

Anmerkung 1: Eine Relation beschreibt eine Beziehung zwischen Codelisten-Einträgen, z.B. welche Gemeinde zu welchem Bezirk gehört (welcher Eintrag einer Gemeinde-Codeliste zu welchem Eintrag einer Bezirks-Codeliste in Beziehung steht).

Anmerkung 2: Die Operation liefert die Einträge mit Informationen zu deren Gültigkeit (Gültigkeitsbeginn, Gültigkeitsende), und liefert die Relation mit der gesamten Historie aller Einträge, inklusive zum Abfragezeitpunkt nicht mehr gültiger oder noch nicht gültiger Einträge.

Anmerkung 3: Das Ergebnis der GetMappingByID-Operation enthält lediglich die IDs (Schlüssel) der durch die Relation einander zugeordneten Codelisten-Einträge. Das Ergebnis enthält die sonstigen zu Codelisten-Einträgen gehörenden Werte NICHT, z.B. Namen oder Beschreibungen. Aus diesem Grund gibt es im Input der GetMappingByID-Operation, im Gegensatz zur GetCodeListByID-Operation, KEINEN Parameter zur Auswahl einer Sprache.

Port-Typ

CodeListPortType

Input

🠖cls:GetMappingByIDRequest

Der Operations-Input besteht aus der 4-stelligen Nummer der vom Webservice auszuliefernden Relation.

Output

🠖cls:GetMappingByIDResponse

Der Operations-Output besteht aus den Einträgen der abgefragten Relation.

Anmerkung: Die Operation liefert die Relations-Inhalte im standardisierten Genericode-XML-Datenformat, http://docs.oasis-open.org/codelist/cs-genericode-1.0/doc/oasis-code-list-representation-genericode.html.

Fault

🠖cls:Failure

Wenn bei der Verarbeitung des GetMappingByID-Aufrufs ein Fehler auftritt, dann reagiert das Webservice mit einem SOAP 1.1 Fault. Das Webservice kann eines oder mehrere der folgenden in SOAP 1.1 definierten Fault-Elemente zur näheren Beschreibung des Fehlers nutzen:

  • faultcode
  • faultstring
  • detail mit Failure-Element-Inhalt

GetLatestChangeDates

Die Operation liefert das Datum der letzten Änderung von Codelisten und/oder Relationen. Als Parameter wird die 4-stellige Nummer der Referenzliste bzw. Relation erwartet.

Port-Typ

CodeListPortType

Input

🠖cls:GetLatestChangeDatesRequest

Der Operations-Input besteht aus einer oder mehreren 4-stelligen Nummern von Codelisten und/oder Relationen.

Output

🠖cls:GetLatestChangeDatesResponse

Der Operations-Output enthält der für jede der im Input identifizierten Codelisten und/oder Relationen das Datum der letzten Änderung.

Anmerkung: Es handelt sich bei diesem Datum nicht um das Datum des Gültigkeitsbeginns der Änderung, sondern um das Datum des Eintragens bzw. Übernehmens der jüngsten Änderung in die edm.gv.at Referenzdaten.

Fault

🠖cls:Failure

Wenn bei der Verarbeitung des GetLatestChangeDates-Aufrufs ein Fehler auftritt, dann reagiert das Webservice mit einem SOAP 1.1 Fault. Das Webservice kann eines oder mehrere der folgenden in SOAP 1.1 definierten Fault-Elemente zur näheren Beschreibung des Fehlers nutzen:

  • faultcode
  • faultstring
  • detail mit Failure-Element-Inhalt

Inputs und Outputs der Webservice-Operationen (aus codelist_webservice_types.xsd)

Inhalt

Beschreibung der mit der XML Schema Definitions-Datei codelist_webservice_types.xsd definierten XML-Datenformate. Die Beschreibung umfasst:

  1. Syntax: Datenelement-Namen, Strukturen, Substrukturen, Datentypen mit Wertebereichen
  2. Semantik: Definition der Bedeutung der Inhalte jedes Datenelements

Es handelt sich hierbei um eine automatisiert aus der annotierten XSD-Datei ↗codelist_webservice_types_annot.xsd generierte Beschreibung. Es ist daher möglich, alternativ zu dieser Beschreibung direkt die annotierte XSD-Datei zu verwenden, z.B. mit einem XML Schema Werkzeug oder einem Texteditor.

Verzeichnis

Strukturen

GetCodeListByIDRequest

GetCodeListByIDResponse

GetMappingByIDRequest

GetMappingByIDResponse

GetLatestChangeDatesRequest

GetLatestChangeDatesResponse

Failure

Substrukturen

CodeListLatestChangeDateType

Datentypen

NonNegative4DigitInteger

Token2

Strukturen

GetCodeListByIDRequest

GetCodeListByIDRequest Schema diagram

Input der GetCodeListByID-Operation.

Name/Typmin..maxDefinition

CodeListID

cls:NonNegative4DigitInteger

1..1

4-stellige Nummer der abzurufenden Codeliste.

Anmerkung: Die Codelisten-Veröffentlichung auf edm.gv.at, sowie die Beschreibungen der edm.gv.at Datenschnittstellen enthalten die 4-stelligen Codelisten-Nummern, die als Parameter für GetCodeListByID-Aufrufe geeignet sind.

Beispielwerte:

  • 3862 für die auf ISO 3166-1 basierende Länder-Liste
  • 7447 für die Liste österreichischer Grenzübergänge

LanguageID

cls:Token2

1..1

ID der Sprache, in welcher das Webservice die Codeliste ausliefern soll.

Anmerkung 1: Die an dieser Stelle unterstützten Werte stammen aus der ↗Codeliste 7632, welche die ISO 639 Liste von Sprachen abbildet.

Anmerkung 2: Für alle der in edm.gv.at verwalteten Codelisten stehen Inhalte, z.B. Namen und Beschreibungen, auf Deutsch zur Verfügung. Für einen Teil der Codelisten, insbesondere für die im Abfallverbringungs-Kontext genutzten Codelisten, stehen die Inhalte zusätzlich auf Englisch zur Verfügung.

Anmerkung 3: Fordert der Client vom Webservice eine Sprache an, in welcher die Codeliste in edm.gv.at NICHT zur Verfügung steht, dann reagiert die Operation mit einem SOAP-Fault.

Beispielwerte:

  • »de« für Deutsch
  • »en« für Englisch

GetCodeListByIDRequest wird verwendet in: 🠖GetCodeListByID

GetCodeListByIDResponse

GetCodeListByIDResponse Schema diagram

Output der GetCodeListByID-Operation.

Name/Typmin..maxDefinition

CodeList

🠖gc:CodeListDocument

1..1

Die angeforderte Codeliste im Genericode-CodeListDocument-Format.

Anmerkung 1: Das Webservice liefert die Codeliste mit allen für die Codeliste in edm.gv.at definierten Spalten aus. Diese Spalten können sich von Codeliste zu Codeliste unterscheiden. Beispielsweise kann eine Liste zusätzlich zu IDs/Schlüsseln lediglich Bezeichnungen enthalten, eine andere aber Bezeichnungen und Beschreibungen. Einheitlich ist hingegen, dass das Webservice zu ALLEN abgerufenen Codelisten die folgenden Spalten liefert, im folgenden mit ihren deutschsprachigen Bezeichnungen benannt:

  • Spalten »Datum_Gueltigkeitsbeginn« und »Datum_Gueltigkeitsende«, welche den Gültigkeitsbeginn bzw. das Gültigkeitsende des jeweiligen Codelisten-Eintrags im xs:date-Format YYYY-MM-DD enthalten. Für undefinierten Gültigkeitsbeginn bzw. undefiniertes Gültigkeitsende enthalten diese Spalten KEINEN WERT, d.h. KEIN »SimpleValue«-Element
  • Spalten »Gueltigkeitsbeginn« und »Gueltigkeitsende«: Die Inhalte dieser Spalten stimmen mit jenen aus »Datum_Gueltigkeitsbeginn« und »Datum_Gueltigkeitsende« überein, sind aber vom Typ xs:string und enthalten das jeweilige Datum im DD.MM.YYYY-Format. Für undefinierten Gültigkeitsbeginn bzw. undefiniertes Gültigkeitsende enthalten diese Spalten einen Leer-String, also ein »SimpleValue«-Element ohne Inhalt.

Anmerkung 2: Das Webservice liefert die »Gueltigkeitsbeginn« und »Gueltigkeitsende«-Spalten aus Gründen der Abwärtskompatibilität aus. Neue Anbindungen an das Codelisten-Webservice SOLLEN diese beiden Spalten IGNORIEREN, und stattdessen für das Auslesen der Gültigkeit ausschließlich die Spalten »Datum_Gueltigkeitsbeginn« und »Datum_Gueltigkeitsende« nutzen.

GetCodeListByIDResponse wird verwendet in: 🠖GetCodeListByID

GetMappingByIDRequest

GetMappingByIDRequest Schema diagram

Input der GetMappingByID-Operation.

Name/Typmin..maxDefinition

CodeListID

cls:NonNegative4DigitInteger

1..1

4-stellige Nummer der abzurufenden Relation.

Anmerkung 1: Eine Relation beschreibt eine Beziehung zwischen den Einträgen zweier Codelisten, z.B. eine Ortschaft-zu-Postleitzahl-Beziehung.

Anmerkung 2: Die Beschreibungen der edm.gv.at Datenschnittstellen enthalten die 4-stelligen Relations-Nummern, die als Parameter für GetMappingByID-Aufrufe geeignet sind.

Beispielwerte:

  • 8168 für die Relation zwischen österreichischen Ortschaften und Postleitzahlen

GetMappingByIDRequest wird verwendet in: 🠖GetMappingByID

GetMappingByIDResponse

GetMappingByIDResponse Schema diagram

Output der GetMappingByID-Operation.

Name/Typmin..maxDefinition

CodeList

🠖gc:CodeListDocument

1..1

Die angeforderte Relation im Genericode-CodeListDocument-Format.

Anmerkung 1: Das Webservice liefert die Relation mit den folgenden Spalten aus:

  • ID (Schlüssel), welcher den einen der beiden einander zugeordneten Codelisten-Einträge identifiziert. Z.B. Ortschaftskennzahl für jene Relation, welche die Beziehung zwischen Ortschaften und Postleitzahlen beschreibt
  • ID (Schlüssel), welcher den anderen der beiden einander zugeordneten Codelisten-Einträge identifiziert. Z.B. Postleitzahl für jene Relation, welche die Beziehung zwischen Ortschaften und Postleitzahlen beschreibt
  • Spalten »Datum_Gueltigkeitsbeginn« und »Datum_Gueltigkeitsende«, welche den Gültigkeitsbeginn bzw. das Gültigkeitsende der einzelnen Beziehung zwischen Codelisten-Einträgen im xs:date-Format YYYY-MM-DD enthalten. Für undefinierten Gültigkeitsbeginn bzw. undefiniertes Gültigkeitsende enthalten diese Spalten KEINEN WERT, d.h. KEIN »SimpleValue«-Element
  • Spalten »Gueltigkeitsbeginn« und »Gueltigkeitsende«: Die Inhalte dieser Spalten stimmen mit jenen aus »Datum_Gueltigkeitsbeginn« und »Datum_Gueltigkeitsende« überein, sind aber vom Typ xs:string und enthalten das jeweilige Datum im DD.MM.YYYY-Format. Für undefinierten Gültigkeitsbeginn bzw. undefiniertes Gültigkeitsende enthalten diese Spalten einen Leer-String, also ein »SimpleValue«-Element ohne Inhalt.

Anmerkung 2: Die Arten von IDs/Schlüsseln in den beiden ID/Schlüssel-Spalten des Operations-Outputs sind im Allgemeinen von Relation zu Relation unterschiedlich, und hängen davon ab, welche IDs/Schlüssel edm.gv.at für die zugrundeliegenden Codelisten enthält.

Anmerkung 3: Das Webservice liefert die »Gueltigkeitsbeginn« und »Gueltigkeitsende«-Spalten aus Gründen der Abwärtskompatibilität aus. Neue Anbindungen an das Codelisten-Webservice SOLLEN diese beiden Spalten IGNORIEREN, und stattdessen für das Auslesen der Gültigkeit ausschließlich die Spalten »Datum_Gueltigkeitsbeginn« und »Datum_Gueltigkeitsende« nutzen.

GetMappingByIDResponse wird verwendet in: 🠖GetMappingByID

GetLatestChangeDatesRequest

GetLatestChangeDatesRequest Schema diagram

Input der GetLatestChangeDates-Operation.

Name/Typmin..maxDefinition

CodeListID

cls:NonNegative4DigitInteger

1..*

4-stellige Nummern der Codeliste und Relationen, für welche das Webservice das Datum der jüngsten Änderung liefern soll.

Anmerkung 1: Die Codelisten-Veröffentlichung auf edm.gv.at, sowie die Beschreibungen der edm.gv.at Datenschnittstellen enthalten die 4-stelligen Nummern von Codelisten und Relationen, die als Parameter für GetLatestChangeDates-Aufrufe geeignet sind.

Anmerkung 2: Die XML-Struktur des GetLatestChangeDatesRequest-Input unterscheidet NICHT zwischen Relationen und Codelisten. Sowohl für Codelisten als auch für Relationen erwartet die Operation die ID im Element CodeListID. Ob das Webservice das jüngste Änderungsdatum für eine Codeliste oder für eine Relation liefern soll, unterscheidet die Webservice-Operation ausschließlich anhand der 4-stelligen Nummer selbst, d.h. daran, ob diese 4-stellige Nummer in edm.gv.at eine Codeliste oder eine Relation identifiziert.

Beispielwerte:

  • 3862 für die auf ISO 3166-1 basierende Länder-Liste
  • 7447 für die Liste österreichischer Grenzübergänge
  • 8168 für die Relation zwischen österreichischen Ortschaften und Postleitzahlen

GetLatestChangeDatesRequest wird verwendet in: 🠖GetLatestChangeDates

GetLatestChangeDatesResponse

GetLatestChangeDatesResponse Schema diagram

Output der GetLatestChangeDates-Operation.

Name/Typmin..maxDefinition

CodeListLatestChangeDate

cls:CodeListLatestChangeDateType

1..*

Kombination aus 4-stelliger Nummer und jüngstem Datum der Änderung, für jede der im Operations-Input identifizierte Codeliste bzw. Relation.

GetLatestChangeDatesResponse wird verwendet in: 🠖GetLatestChangeDates

Failure

Failure Schema diagram

Failure-Struktur, welches das Webservice in SOAP 1.1 Faults im SOAP 1.1 Element »detail« verwendet.

Name/Typmin..maxDefinition

Code

xs:string

1..1

ID aus ↗Codeliste 5156, welche die Art des aufgetretenen Fehlers klassifiziert.

Beispielwert: »101.a« i.Z. mit fehlenden oder unpassenden Authentifizierungsdaten

Reason

xs:string

1..1

Natürlichsprachige Bezeichnung des aufgetretenen Fehlers.

Beispielwert: »Fehlende oder unpassende Authentifizierungsdaten«

Detail

xs:string

0..1

Natürlichsprachige Detailbeschreibung des aufgetretenen Fehlers.

Failure wird verwendet in: 🠖GetCodeListByID, 🠖GetLatestChangeDates, 🠖GetMappingByID

Substrukturen

CodeListLatestChangeDateType

CodeListLatestChangeDateType Schema diagram

Kombination aus 4-stelliger Nummer einer Codeliste/Relation sowie Datum der jüngsten Änderung der betreffenden Codeliste/Relation.

Name/Typmin..maxDefinition

CodeListID

cls:NonNegative4DigitInteger

1..1

4-stellige Nummer der Codeliste bzw. Relation.

Beispielwerte:

  • 3862 für die auf ISO 3166-1 basierende Länder-Liste
  • 7447 für die Liste österreichischer Grenzübergänge
  • 8168 für die Relation zwischen österreichischen Ortschaften und Postleitzahlen

LatestChangeDate

xs:date

1..1

Jüngstes Änderungsdatum für die jeweilige per 4-stelliger Nummer identifizierte Codeliste bzw. Relation.

Beispielwert: »2023-01-05«

Anmerkung: Allfällig vom Webservice zum Datum mit ausgelieferte Zeitzonen-Information besitzt keine definierte Bedeutung. Entwickler sollen solche Information bei der Umsetzung einer Anbindung an das Webservice daher ignorieren.

CodeListLatestChangeDateType wird verwendet in: GetLatestChangeDatesResponse

Datentypen

NonNegative4DigitInteger

Name/Typmin..maxDefinition

NonNegative4DigitInteger

xs:integer

1..1

Identifikation einer in edm.gv.at verwalteten Codeliste oder Relation per 4-stelliger Nummer.

Beispielwerte:

  • 3862 für die auf ISO 3166-1 basierende Länder-Liste
  • 7447 für die Liste österreichischer Grenzübergänge
  • 8168 für die Relation zwischen österreichischen Ortschaften und Postleitzahlen

NonNegative4DigitInteger wird verwendet in: CodeListLatestChangeDateType, GetCodeListByIDRequest, GetLatestChangeDatesRequest, GetMappingByIDRequest

Token2

Name/Typmin..maxDefinition

Token2

xs:NMTOKEN

1..1

Identifikation einer Sprache (↗Codeliste 7632).

Beispielwerte:

  • »de« für Deutsch
  • »en« für Englisch

Token2 wird verwendet in: GetCodeListByIDRequest

Message-Formate (aus genericode_excerpt.xsd)

Inhalt

Beschreibung der mit der XML Schema Definitions-Datei genericode_excerpt.xsd definierten XML-Datenformate. Die Beschreibung umfasst:

  1. Syntax: Datenelement-Namen, Strukturen, Substrukturen, Datentypen mit Wertebereichen
  2. Semantik: Definition der Bedeutung der Inhalte jedes Datenelements

Es handelt sich hierbei um eine automatisiert aus der annotierten XSD-Datei ↗genericode_excerpt_annot.xsd generierte Beschreibung. Es ist daher möglich, alternativ zu dieser Beschreibung direkt die annotierte XSD-Datei zu verwenden, z.B. mit einem XML Schema Werkzeug oder einem Texteditor.

Verzeichnis

Strukturen

CodeListDocument

Substrukturen

Agency

Annotation

AnyOtherLanguageContent

Column

ColumnSet

Data

Identification

Key

KeyColumnRef

Row

SimpleCodeList

Value

Datentypen

DatatypeFacet

GeneralIdentifier

LongName

MimeTypedUri

ShortName

SimpleValue

UseType

Strukturen

CodeListDocument

CodeListDocument Schema diagram

Document type for genericode code list definitions.

Name/Typmin..maxDefinition

Annotation

gc:Annotation

0..1

User annotation information.

Identification

gc:Identification

1..1

Identification and location information (metadata).

ColumnSet

gc:ColumnSet

1..1

Definition of a column set (columns and keys for the code list).

SimpleCodeList

gc:SimpleCodeList

0..1

Simple (explicit) code list definition.

CodeListDocument wird verwendet in: 🠖GetCodeListByIDResponse, 🠖GetMappingByIDResponse

Substrukturen

Agency

Agency Schema diagram

Details of an agency which produces code lists or related artifacts.

Name/Typmin..maxDefinition

ShortName

gc:ShortName

0..1

Short name (without whitespace) for the agency.

LongName

gc:LongName

0..*

Human-readable name for the agency.

Identifier

gc:GeneralIdentifier

0..*

Identifier for the agency.

Agency wird verwendet in: Identification

Annotation

Annotation Schema diagram

User annotation information.

Name/Typmin..maxDefinition

Description

gc:AnyOtherLanguageContent

0..*

Human-readable information.

Annotation wird verwendet in: CodeListDocument, Column, Data, Key, KeyColumnRef

AnyOtherLanguageContent

AnyOtherLanguageContent Schema diagram

Container for any human-readable XML content which is in a different namespace to the Schema's target namespace.

Name/Typmin..maxDefinition

AnyOtherLanguageContent wird verwendet in: Annotation

Column

Column Schema diagram

Definition of a column.

Each column of a code list defines a piece of metadata that can be specified for each item in the code list.

Name/Typmin..maxDefinition

@Id

xs:ID

1..1

Unique ID within the document.

@Use

gc:UseType

1..1

Whether the usage is required or optional.

Annotation

gc:Annotation

0..1

User information about the column.

ShortName

gc:ShortName

1..1

Short name (without whitespace).

LongName

gc:LongName

0..*

Human-readable name.

CanonicalUri

xs:anyURI

1..1

Canonical URI which uniquely identifies all versions collectively.

CanonicalVersionUri

xs:anyURI

0..1

Canonical URI which uniquely identifies this version.

Data

gc:Data

1..1

Data type of the column.

Column wird verwendet in: ColumnSet

ColumnSet

ColumnSet Schema diagram

Definition of a column set (columns and keys for a code list).

Name/Typmin..maxDefinition

Column

gc:Column

0..*

Definition of a column.

Key

gc:Key

0..*

Definition of a key.

ColumnSet wird verwendet in: CodeListDocument

Data

Data Schema diagram

Data type definition.

Name/Typmin..maxDefinition

@Type

xs:token

1..1

Unique ID for the datatype within its datatype library.

@Lang

xs:language

0..1

Language code which accepts the same values as 'xml:lang'.

Unlike 'xml:lang', the scope of the language definition is not restricted to the XML content within the element where the 'lang' attribute appears.

Annotation

gc:Annotation

0..1

User annotation for the datatype.

Parameter

gc:DatatypeFacet

0..*

Facet parameter which refines the datatype.

Data wird verwendet in: Column

Identification

Identification Schema diagram

Identification and location information (metadata).

Name/Typmin..maxDefinition

ShortName

gc:ShortName

1..1

Short name (without whitespace).

LongName

gc:LongName

0..*

Human-readable name.

Version

xs:token

1..1

Version identifier.

CanonicalUri

xs:anyURI

1..1

Canonical URI which uniquely identifies all versions (collectively).

CanonicalVersionUri

xs:anyURI

1..1

Canonical URI which uniquely identifies this version.

LocationUri

xs:anyURI

0..*

Suggested retrieval location for this version, in genericode format.

AlternateFormatLocationUri

gc:MimeTypedUri

0..*

Suggested retrieval location for this version, in a non-genericode format.

Such alternative formats are intended only as additional renditions of the code list information, not as a replacements nor as alternatives for use in application processing.

Agency

gc:Agency

0..1

Agency that is responsible for publication and/or maintenance of the information.

Identification wird verwendet in: CodeListDocument

Key

Key Schema diagram

Definition of a key.

A key is a set of one or more columns whose values together provide a unique identification of each item in a code list.

Name/Typmin..maxDefinition

@Id

xs:ID

1..1

Unique ID within the document.

Annotation

gc:Annotation

0..1

User annotation for the key.

ShortName

gc:ShortName

1..1

Short name (without whitespace).

LongName

gc:LongName

0..*

Human-readable name.

CanonicalUri

xs:anyURI

1..1

Canonical URI which uniquely identifies all versions collectively.

CanonicalVersionUri

xs:anyURI

0..1

Canonical URI which uniquely identifies this version.

ColumnRef

gc:KeyColumnRef

1..*

Reference to the document ID of a column in the key.

Key wird verwendet in: ColumnSet

KeyColumnRef

KeyColumnRef Schema diagram

Reference to a column which forms part of a key.

Name/Typmin..maxDefinition

@Ref

xs:IDREF

1..1

Reference to the ID of the column within the document.

Annotation

gc:Annotation

0..1

User annotation for the column.

KeyColumnRef wird verwendet in: Key

Row

Row Schema diagram

Row which represents an individual item in a code list.

Name/Typmin..maxDefinition

Value

gc:Value

1..*

Column value for the row.

Row wird verwendet in: SimpleCodeList

SimpleCodeList

SimpleCodeList Schema diagram

Simple (explicit) code list definition.

Name/Typmin..maxDefinition

Row

gc:Row

0..*

Row which represents an individual item in the code list.

SimpleCodeList wird verwendet in: CodeListDocument

Value

Value Schema diagram

An individual code list metadata value.

Name/Typmin..maxDefinition

@ColumnRef

xs:IDREF

0..1

Reference to a column ID in the document.

SimpleValue

gc:SimpleValue

0..1

Simple textual value.

Value wird verwendet in: Row

Datentypen

DatatypeFacet

Name/Typmin..maxDefinition

DatatypeFacet

xs:string

1..1

Facet information for refining a datatype.

@ShortName

xs:token

1..1

Short name (token) for the datatype facet.

@LongName

xs:normalizedString

0..1

Long name for the datatype facet.

DatatypeFacet wird verwendet in: Data

GeneralIdentifier

Name/Typmin..maxDefinition

GeneralIdentifier

xs:normalizedString

1..1

An identifier value. Typically not a long or short name.

@Identifier

xs:normalizedString

0..1

A string which identifies one of a set of alternate values.

@xml:lang

xs:language

0..1

The language from which the value is taken or derived.

GeneralIdentifier wird verwendet in: Agency

LongName

Name/Typmin..maxDefinition

LongName

xs:normalizedString

1..1

A human-readable name.

@Identifier

xs:normalizedString

0..1

A string which identifies one of a set of alternate values.

@xml:lang

xs:language

0..1

The language from which the value is taken or derived.

LongName wird verwendet in: Agency, Column, Identification, Key

MimeTypedUri

Name/Typmin..maxDefinition

MimeTypedUri

xs:anyURI

1..1

URI for a resource, with support for specifying the MIME type.

@MimeType

xs:normalizedString

0..1

MIME type of the resource which can be retrieved from the URI.

MimeTypedUri wird verwendet in: Identification

ShortName

Name/Typmin..maxDefinition

ShortName

xs:token

1..1

A short name without whitespace that is suitable for use in generating names for software artifacts.

@xml:lang

xs:language

0..1

The language from which the short name is taken or derived.

ShortName wird verwendet in: Agency, Column, Identification, Key

SimpleValue

Name/Typmin..maxDefinition

SimpleValue

xs:string

1..1

Simple textual value.

SimpleValue wird verwendet in: Value

UseType

Name/Typmin..maxDefinition

UseType

xs:token

1..1

Indicates whether the usage is required or optional.

UseType wird verwendet in: Column

Spezifikations-Änderungsverzeichnis

Änderungsverzeichnis

VersionDatumBeschreibung / Änderungen
1.012023‑03‑01

Änderungen:

  1. Die Umsetzung der Spezifikation 1.00 für das edm.gv.at Codelisten Abfrage Webservice wies einen Fehler insofern auf, als das Webservice die Gültigkeit von Listen- und Relations-Einträgen in den Spalten Gueltigkeitsbeginn und Gueltigkeitsende trotz Deklaration als date-Spalte im Format DD.MM.YYYY ausgeliefert hat. Die Spezifikation 1.01 behebt dies auf folgende Weise:
    • Die Spalten Gueltigkeitsbeginn und Gueltigkeitsende bleiben aus Abwärtskompatibilitätsgründen mit Datumsangaben im DD.MM.YYYY-Format erhalten. Das Webservice liefert diese Spalten aber nunmehr als Spalten des Typs string aus, so dass es keinen Widerspruch mehr zwischen Typ und Inhalt der Spalten gibt
    • Das Webservice liefert die Gültigkeit nunmehr in zwei weiteren Spalten zusätzlich aus. Dabei handelt es sich um die Spalten Datum_Gueltigkeitsbeginn und Datum_Gueltigkeitsende. Diese deklariert das Webservice als date-Spalten. Das Webservice liefert die Inhalte dieser Spalten im YYYY‑MM‑DD-Format aus
  2. Die XML-Beispieldateien des Spezifikationspakets so angepasst, dass sie die im vorigen Punkt beschriebene Änderung wiedergeben, d.h. die Ergänzung von Datumsspalten
  3. Das Spezifikationspaket enthält nun nicht mehr die unverändert aus dem Genericode-Standard übernommene XSD-Datei genericode.xsd, sondern eine daraus abgeleitete Datei genericode_excerpt.xsd. Diese enthält nur jenen Teil der XML-Strukturen des Genericode-Standard, welchen die Codelisten-Webservice-Spezifikation tatsächlich verwendet
  4. Neue Strukturierung und Benennung der zum Paket gehördenden Dateien und Ordner, sowie eine HTML-Beschreibung der Operationen und deren Inputs und Outputs, als Maßnahme zur Vereinheitlichung der edm.gv.at-Spezifikationspakete
1.002014‑11‑27

Erstveröffentlichung