diff --git a/docs/details/reference-schemas.md b/docs/details/reference-schemas.md index ec99c1f0dd384858f0bca410e633f4044e898ab5..d424f37af5abc438aa43584c57ba69639141c13c 100644 --- a/docs/details/reference-schemas.md +++ b/docs/details/reference-schemas.md @@ -2,6 +2,8 @@ Im Folgenden wird aufgezeigt, wie Fachschemarerenzen für Fachdatensätze auf bestehende Fachstandards und Rahmenwerke abgebildet werden. Aktuell werden folgende Fachstandards und Rahmenwerke beschrieben: +- FIM Übertragungsschemata für Anträge auf Basis von FIM Datenfelder +- XÖV Nachrichten auf Basis von XÖV-konformen Fachstandards Soll ein anderer Fachstandard mit der FIT-Conect Submission API übermittelt werden, können wir gerne die Beschreibung dieser Schemareferenz hier aufnehmen, um diese Informationen einem breiteren Nutzerkreis zugänglich zu machen. Hierzu bitte einfach Issue [hier](https://git.fitko.de/fit-connect/docs) aufmachen diff --git a/docs/getting-started/receiving/validate.mdx b/docs/getting-started/receiving/validate.mdx index 10a73079e48237e075b4d46f84f2e9217573ccf4..d5ad1e2d6fe9128e6097c193c9403752832edcba 100644 --- a/docs/getting-started/receiving/validate.mdx +++ b/docs/getting-started/receiving/validate.mdx @@ -1,8 +1,9 @@ --- sidebar_position: 7 -title: Validierung des Metadatensatz +title: Schemavalidierung --- +## Validierung der Metadatensatzes Das Minimum, was an Information in den Metadaten vorhanden sein muss, sind die Felder `authenticationInformation` und `contentStructure`. Zusätzlich können noch die Felder `paymentInformation`, `publicServiceType` und `replyChannel` mit entsprechenden Unterobjekten angegeben werden, um den Weg einer Antwort bzw. die Bezahlinformationen der Einreichung @@ -10,3 +11,133 @@ genauer zu definieren. Die gültigen Formate, die die Felder des Schemas annehme [Schema selbst](../../apis/metadata.mdx) definiert und können mithilfe von Bibliotheken für die Validierung einer Instanz von Antragsmetadaten verwendet werden. Eine Liste der zur Verfügung stehenden Validatoren ist auf der [offiziellen Seite](https://json-schema.org/implementations.html#validators) von JSON-Schema zu finden. + +## Validierung des Fachdatensatz + +Danach erfolgt eine Prüfung des Fachdatensatzes: +- Entspricht der Fachdatensatz dem vereinbarten Medientyp (JSON oder XML)? +- Entspricht der Fachdatensatz dem vereinbarten Schema? + +Hierbei kann die im Metadatensatz enthaltene Schemareferenz genutzt werden, um das zu validierende Schema zu identifizieren, falls der Zustellpunkt mehrere +Schemata unterschützt. + +Das Validierungsvorgehen wird im folgenden Anhand von FIM und XÖV Beispielen gezeigt. + +### Details zur Prüfung eines FIM Fachdatensatzes (JSON Schema) + +:::caution +Das FITKO Schemarepository ist derzeit noch in Vorbereitung. +Daher können die Fachschemata noch nicht wie beschrieben heruntergeladen werden. + +Die JSON Variante des FIM Fachdatensatzes befindet sich ebenfalls noch in der Konzeption und kann noch nicht genutzt werden. +::: + +Die FIM-Fachschemata werden im FITKO Schemarepository (`https://schema.fitko.de/`) abgelegt. +Die Fachschemareferenz gibt an, welches Schema zu beziehen ist. + +```json + "contentStructure": { + "data": { + "schema": { + "schemaURI": "https://schema.fitko.de/fim/s00000000009_1.0.0.schema.json", + "mimeType": "application/json" + } +``` + +- Prüfen Sie, dass die `schemaURI` mit `https://schema.fitko.de/fim/` beginnt. Dies stellt sicher, dass das Fachschema aus dem FITKO Repository bezogen wird. +- Laden Sie das Fachschema herunter + +``` +➜ wget -nv https://schema.fitko.de/fim/s00000000009_1.0.0.schema.json +``` + +- Nun können Sie den Fachdatensatz gegen das vorliegende Fachschema "s00000000009_1.0.0.schema.json" prüfen. + +### Details zur Prüfung eines FIM Fachdatensatzes (XML Schema) + +Die Fachschemata von XFall können über das FIM-Portal bezogen werden. +Zukünftig werden sie auch über das FITKO Schemarepository zur Verfügung stehen. + +```json + "contentStructure": { + "data": { + "schema": { + "schemaURI": "https://schema.fitko.de/fim/s00000092_1.0.xsd", + "mimeType": "application/xml" + } +``` + +- Prüfen Sie, dass die `schemaURI` mit `https://schema.fitko.de/fim/` beginnt. +- Entnehmen Sie der URI die ID des Fachschemas (hier: "s00000092"). +- Öffnen Sie das FIM-Portal (https://fimportal.de/) und loggen Sie sich ein. +- Öffnen Sie Sie Adresse `https://fimportal.de/detail/D/{ID}`, also z.B. https://fimportal.de/detail/D/S00000092. +- Klicken Sie rechts auf den Downloadlink, der auf "_xfall.xsd" endet (hier: `S00000092V1.0_xfall.xsd`). +- Das XFall-Schema wird Ihnen angezeigt und kann abgespeichert werden. +- Nun können Sie den Fachdatensatz gegen das vorliegende Fachschema "S00000092V1.0_xfall.xsd" prüfen. + +### Details zur Prüfung eines XÖV Fachdatensatzes + +Die XÖV Standards werden im [XRepository](https://www.xrepository.de/) abgelegt. +Auf die Inhalte des XRepository kann über eine [REST-API](https://www.xrepository.de/cms/hilfe.html#rest-api) zugegriffen werden. +Entnehmen Sie der Fachschemareferenz die Angabe `schemaURI`. Diese besteht aus zwei durch ein Doppelkreuz (#) getrennten Teilen. Vor dem Doppelkreuz steht die Kennung, dahinter der Name der Nachricht. +Um z.B. einen Bauantrag zu prüfen, gehen Sie wie folgt vor. +- Im Metadatensatz finden Sie folgende Fachschemareferenz. + +```json + "contentStructure": { + "data": { + "schema": { + "schemaURI": "urn:xoev-de:bmk:standard:xbau_2.2#baugenehmigung.antrag.0200", + "mimeType": "application/xml" + } +``` + +- Die `schemaURI` enthält folgende Angaben: + - Kennung: `urn:xoev-de:bmk:standard:xbau_2.2` + - Nachrichtenname `baugenehmigung.antrag.0200` +- Laden Sie das XML Schema herunter und entpacken Sie es. + +``` +➜ wget -nv -O xmlschema.zip https://www.xrepository.de/api/version_standard/urn:xoev-de:bmk:standard:xbau_2.2/xmlschema +2021-06-25 15:17:54 URL:https://www.xrepository.de/api/version_standard/urn:xoev-de:bmk:standard:xbau_2.2/xmlschema [278585] -> "xmlschema.zip" [1] +``` + +``` +➜ unzip xmlschema.zip +Archive: xmlschema.zip + inflating: xsd.zip + inflating: xsd_dev.zip +``` + +- Im Falle von XBau 2.2 enthält das XML-Schema zwei Dateien. Enpacken Sie die Datei `xsd.zip`. Dieser Schritt ist XBau-spezifisch und muss bei anderen Standards angepasst werden. + +``` +➜ unzip xsd.zip +Archive: xsd.zip + inflating: xbau-basisdatentypen.xsd + inflating: xbau-baukasten.xsd + inflating: xbau-codes.xsd + inflating: xbau-nachrichten-abweichung.xsd + inflating: xbau-nachrichten-anzeige.xsd + inflating: xbau-nachrichten-baugenehmigung.xsd + inflating: xbau-nachrichten-baulasten.xsd + inflating: xbau-nachrichten-bautechnischeNachweise.xsd + inflating: xbau-nachrichten-bauzustand.xsd + inflating: xbau-nachrichten-beteiligung.xsd + inflating: xbau-nachrichten-genehmigungsfreistellung.xsd + inflating: xbau-nachrichten-informationsempfaenger.xsd + inflating: xbau-nachrichten-kammernverzeichnis.xsd + inflating: xbau-nachrichten-teilbaugenehmigung.xsd + inflating: xbau-nachrichten-ueberwachungspflichtigeAnlagen.xsd + inflating: xbau-nachrichten-vorbescheid.xsd + inflating: xbau-prozessnachrichten.xsd +``` + +- Suchen Sie nun nach der Datei, die die Elementdefinition der geforderten Nachricht enthält. + +``` +➜ grep -l 'name=.baugenehmigung.antrag.0200' *.xsd +xbau-nachrichten-baugenehmigung.xsd +``` + +- Nun können Sie den Fachdatensatz gegen das vorliegende Fachschema "xbau-nachrichten-baugenehmigung.xsd" prüfen. diff --git a/docs/getting-started/submission-structure.md b/docs/getting-started/submission-structure.md index e29c229653988a95c9364bf6c6ef5139b5b03e0b..884aa90344c4409697e7520c9356bc112ad3a22f 100644 --- a/docs/getting-started/submission-structure.md +++ b/docs/getting-started/submission-structure.md @@ -30,22 +30,24 @@ In der Submission API wird ein konkretes Schema für den Fachdatensatz durch das In den Angaben eines Zustellpunkts befindet es diese Schemareferenz immer innerhalb eines Service Objekts innerhalb des `services` Arrays. Die Schemarefenz ist daher immer in einer dazugehörigen Leistung zugeordnet. ```json - -"services": [ + "submissionSchemas": [ { - "identifier": "urn:de:fim:leika:leistung:99010003001006", - "submissionSchemas": [ - { - "schemaURI": "https://schema.fitko.de/fim/s00000121_1.0.0.schema.json", - "mimeType": "application/json" - } - ], - "regions": [ - "DE094750156156", - "DE09330411" - ] -} - + "schemaURI": "https://schema.fitko.de/fim/s00000000009_1.0.0.schema.json", + "mimeType": "application/json" + }, + { + "schemaURI": "https://schema.fitko.de/fim/s00000000009_1.1.0.schema.json", + "mimeType": "application/json" + } + { + "schemaURI": "https://schema.fitko.de/fim/s00000000010_1.0.0.schema.json", + "mimeType": "application/json" + }, + { + "schemaURI": "https://schema.fitko.de/fim/s00000000010_1.1.0.schema.json", + "mimeType": "application/json" + } + ], ``` Wenn ein sendendes System die Angaben eines Zustellpunkts ermittelt (bspw. über GET /destinations/{destinationId} oder zukünftig die Routing API), so muss der Fachdatensatz diesem Schema entsprechen. Wenn mehrere Schemata innerhalb des `submissionSchemas` Array @@ -60,7 +62,7 @@ Zusätzlich muss das sendende System in den Metadaten der Einreichung eine ident "contentStructure": { "data": { "submissionSchemas": { - "schemaURI": "https://schema.fitko.de/fim/s00000121_1.0.0.schema.json", + "schemaURI": "https://schema.fitko.de/fim/s00000000009_1.0.0.schema.json", "mimeType": "application/json" } },