Merge branch 'document-application-metadata-scheme' into 'master'

Erste Dokumentation des Antragsmetadatenschemas

See merge request fit-connect/api!27

.gitlab-ci.yml

@@ -16,9 +16,18 @@ build:
   stage: build
   image: $CI_REGISTRY/node:current-alpine
   before_script:
+    - echo 'http://dl-cdn.alpinelinux.org/alpine/edge/community' >> /etc/apk/repositories
+    - apk update
+    - apk add yq bash
+    - yq -V
     - npm install -g @apidevtools/swagger-cli
     - mkdir dist
-  script: swagger-cli bundle -t yaml -o dist/zustelldienst.yml spec/zustelldienst.yml
+  script:
+    - ./bundle-docs.sh
+    - yq e '.info.description.$ref = "../dist/docs.bundled.md"' -i spec/zustelldienst.yml
+    - cp metadata-schema/antragsmetadaten.schema.json dist/
+    - swagger-cli bundle -t yaml -o dist/zustelldienst.yml spec/zustelldienst.yml
+    - yq e '.components.schemas.Antragsmetadaten.$ref = "./antragsmetadaten.schema.json"' -i dist/zustelldienst.yml
   # find ./spec -type f -name "*.yml" -exec sh -c 'swagger-cli bundle -t yaml -o dist/$(basename {}) {}' \;
   artifacts:
     expose_as: 'Built API spec'
@@ -42,8 +51,11 @@ upload:
     - chmod 700 ~/.ssh
     - echo "$UBERSPACE_KNOWN_HOST" >> ~/.ssh/known_hosts
   script:
-    - sed "s,REPLACEME,$CI_COMMIT_TAG/zustelldienst.yml,g" ui/config.js.template > ui/config.js
+    - sed "s,API_VERSION,$CI_COMMIT_TAG/zustelldienst.yml,g" ui/config.js.template > ui/config.js
+    - sed "-i "s,API_VERSION,$CI_COMMIT_TAG" dist/zustelldienst.yml
+    - sed "-i "s,API_VERSION,$CI_COMMIT_TAG" dist/antragsmetadaten.schema.json
     - rsync -rLvz --size-only --checksum -e "ssh -o CheckHostIP=no" --ipv4 --progress ./ui/. fitko@dorado.uberspace.de:html/
+    - rsync -rLvz --size-only --checksum -e "ssh -o CheckHostIP=no" --ipv4 --progress ./assets/. fitko@dorado.uberspace.de:html/$CI_COMMIT_TAG/
     - rsync -rLvz --size-only --checksum -e "ssh -o CheckHostIP=no" --ipv4 --progress ./dist/. fitko@dorado.uberspace.de:html/$CI_COMMIT_TAG/
 
 #release-new-api-version:

.spectral.yml

@@ -11,3 +11,7 @@ rules:
   response-with-json-object: error
   paths-status-return-problem: off
   paths-status-problem-schema: off
+
+except:
+  '#/info/version':
+    - use-semver
\ No newline at end of file

bundle-docs.sh

+#!/usr/bin/env bash
+
+mkdir -p dist
+
+# Concatenate all files (enforce newline between files)
+cut -b 1- docs/_* docs/{1..5}_* docs/Detailinformationen/*.md > dist/docs.bundled.md
+# Add additional newlines before each heading (to avoid issues when, e.g., a table is followed by a heading)
+sed -i 's/^#/\n\n#/g' dist/docs.bundled.md

docs/1_Getting_Started.md

 # Erste Schritte zur API Nutzung
 
-<!-- theme: info -->
+## ① Account registrieren
 
-> ## ① Account registrieren
 > Registrieren Sie sich für ein Zugriff, um mit Ihren Client auf die API zuzugreifen. Im Rahmen der Registrierung bekommen Sie für die gewünschte API die Client-ID und Zugriffdaten mitgeteilt. Da zum aktuellen Zeitpunkt keine Sandbox Umgebung bereitstellt, wird empfohlen, sich für beide Seiten zu registieren, um für komplexere Tests mit einem REST Client die API der Gegenseite anzusprechen (Siehe Postman Nutzung in Schritt 2). ➡ [Registrierung zur API Nutzung](./4_Authentifizierung_und_Autorisierung.md)
 
-> ## ② API ausprobieren
-> In der Navigation auf linken Seite finden Sie die jeweiligen API Referenzen für die Nutzung der APIs unter den Reitern `Application Sender API` und `Application Subscriber API` 
-Für einen einfachen Einstieg zum Test der API können Sie die bereitgestellte Postman Collection nutzen und mit dem Postman REST Client die Anfragen an die API durchführen. Hiermit können Sie auch die Gegenseite (Sender oder Empfänger von Anträgen simulieren) (➡ [Testen mit Postman](./Detailinformationen/Postman.md). Nähere Informationen zu Postman siehe https://www.postman.com/) 
+## ② API ausprobieren
+
+> In der Navigation auf linken Seite finden Sie die jeweiligen API Referenzen für die Nutzung der APIs unter den Reitern `Application Sender API` und `Application Subscriber API`
+Für einen einfachen Einstieg zum Test der API können Sie die bereitgestellte Postman Collection nutzen und mit dem Postman REST Client die Anfragen an die API durchführen. Hiermit können Sie auch die Gegenseite (Sender oder Empfänger von Anträgen simulieren) (➡ [Testen mit Postman](./Detailinformationen/Postman.md). Nähere Informationen zu Postman siehe <https://www.postman.com/>)
 Alternativ können Sie die Anfragen auch mittels eigener Anwendungen oder alternativer REST Clients durchführen.
 
-> ## ③ OAuth Token vor der API Nutzung abrufen
+## ③ OAuth Token vor der API Nutzung abrufen
+
 > Für jede Anfrage an die API Endpunkte ist ein gültiger JWT-Token mit der Anfrage mitzusenden. Für nähere Informationen zum Abruf eines JWT-Token siehe ➡ [OAuth Details](./Detailinformationen/OAuth.md)
 
-> ## ④ Spezifikation lokal nutzen
-> Sofern Sie einen lokalen Zugriff auf die Quellen der Spezifikation im OpenAPI Format (bspw. für Code Generatoren) benötigen, finden Sie diese hier: ➡[FIT-Connect-PoC-v0.6.zip](https://github.com/fiep-poc/assets/raw/master/spec/FIT-Connect-PoC-v0.6.zip)
+## ④ Spezifikation lokal nutzen
 
+> Sofern Sie einen lokalen Zugriff auf die Quellen der Spezifikation im OpenAPI Format (bspw. für Code Generatoren) benötigen, finden Sie diese hier: ➡[FIT-Connect-API-Spec.yml](https://fitko.uber.space/API_VERSION/zustelldienst.yml)
 
 ## Beispiel mit `curl`
 
@@ -44,6 +45,7 @@ curl --silent --header "Authorization: Bearer ${TOKEN}" https://sender-test.fiep
 <!-- theme: success -->
 
 > ### Service Desk
+
 > Für Fragen, Anregungen und sonstiges Feedback steht Ihnen unser
 > [FIT-Connect Service Desk](https://jira.fiep-poc.de/servicedesk/customer/portal/1)
 > zur Verfügung.

docs/Detailinformationen/Callback.md

-# Callback Benachrichtigungen
-
-Callbacks sind einfache Webhooks und dienen dazu, API Nutzer über relevante Ereignisse aktiv zu informieren, anstatt das der Client über konstante Abfragen an der API potentielle Änderungen oder Eigenisse abzufragen muss. 
-
-Aktuell wird den Subscribern eine Callback Funktion angeboten, um diese über abrufbereite Anträge in ihren Destinations zu informieren.
-
-## Callback registrieren
-Beim [anlegen](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations/post) oder [aktualisieren](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}/put) einer Destination sollte ein Callback angegeben werden.
-
-```json
-{
-  "organization": {
-    "organization-name": "Gewerbeamt Musterhausen"
-  },
-  "technical-contact": [
-    {
-      "first-name": "Werner",
-      "last-name": "Mustermann",
-      "contact": {
-        "telephones": [
-          {
-            "number": "+49 89 32168-42",
-            "mobile": false,
-            "type": "work"
-          }
-        ]
-      }
-    }
-  ],
-  "callback": {
-    "callback-url": "https://www.example.com/callback"
-  }
-}
-```
-
-## Callback ausführen
-Trifft nun ein neuer Antrag ein, so sendet der Zustelldienst einen HTTP-POST-Request an die angegebene Adresse. Im Body des Requests werden die `destination-id` und die `application-id`s der wartenden Anträge (i.d.R. genau eine) aufgelistet.
-
-```json
-{
-  "destination-id": "821",
-  "applications": [
-    {
-      "application-id": "98472"
-    }
-  ]
-}
-```
-
-## Callback nur bei Inaktivität
-Nach einem Callback wartet der Zustelldienst eine gewisse Zeit (z.B. 5 Minuten) bis zum nächsten Callback, auch wenn in dieser Zeit neue Anträge eintreffen. Diese Wartezeit wird bei Aktivität der Destination (z.B. Abfrage der Queue oder Abholen von Anträgen) verlängert.

docs/Detailinformationen/Metadaten.md

+# Antragsmetadaten
+
+Die Antragsmetadaten beschreiben die Struktur des Antrags und dessen Inhalte, wie beispielsweise Anhänge oder die Fachdaten. Zustätzlich können weitere Informationen über den/die AntragsstellerInnen hinterlegt werden. Eine genaue Definition ist unter XYZ zu finden bzw. direkt im [Schema](/API_VERSION/antragsmetadaten.schema.json) zu finden.
+
+Im Folgenden wird nun beschrieben, wie für das Versenden eines Antrags das Schema aufgebaut und befüllt wird, sowie beim Empfangen eines Antrags dieser entschlüsselt und gegen das Schema validiert wird.
+
+## Prozess: Versenden eines Antrages
+
+### Anlegen eines neuen Antrags
+
+Das Anlegen eines neuen Antrags kann über die API getätigt werden. Dafür muss ein HTTP POST Nachricht versendet werden, die definiert, an welchen Zustellpunkt der Antrag versendet werden soll und welche Inhalte übermittelt werden sollen. Die Inhalte umfassen hierbei die Identifikatoren der Anhänge als UUIDs und die Information, ob Fachdaten mit versendet werden oder nicht.
+
+```text
+curl --data '{ "destinationId": "<UUID>", "announcedContentStructure": {} }' -H 'Content-Type: application/json' -H 'X-AnwenderId: <Id>' -X POST <URL>/applications/
+```
+
+```text
+curl --data '{ "destinationId": "7a2668ad-3081-407c-9358-7ce4b6144b02", "announcedContentStructure": {"data": "false", "attachments": []} }' -H 'Content-Type: application/json' -H 'X-AnwenderId: sender' -X POST localhost:8080/applications/
+> {
+  "destinationId": "7a2668ad-3081-407c-9358-7ce4b6144b02",
+  "applicationId": "9d618546-0ff7-4e93-9f15-714e5dd1bf12"
+}
+```
+
+### Definition der Antragsmetadaten
+
+Das Minimum, was an Antragsmetadaten hinterlegt werden muss, ist eine Beschreibung der Struktur des Antrags, sowie die ID des Antrags selbst.
+In der Beschreibung der Struktur muss angegeben werden, ob Fachdaten mit versendet werden und in welchem Format diese sind. Des Weiteren können Anhänge mit ihren Metainformationen beschrieben werden, die dem Antrag beigefügt sind.
+
+Ein Beispiel hierfür ist unten dargestellt:
+
+```json
+{
+  "contentStructure": {
+    "data": {
+      "schema": {
+        "mimeType": "application/json",
+        "schemaSource": "https://schema.fitko.de/fim/fim.S00000147.00000147001002.json"
+      }
+    },
+    "docs": [
+      {
+        "docId": "1",
+        "purpose": "form",
+        "size": 13046,
+        "mimeType": "application/pdf",
+        "filename": "test.pdf",
+        "description": "Das Antragsformular",
+        "lang": {
+          "lang": "de",
+          "region": "DE"
+        },
+        "hash": {
+          "algorithm": "SHA-256",
+          "digest": "bf37d894fdf9aeade63975ed648d49c3e8a7a773923597d2418915f54cd7c3b9"
+        }
+      }
+    ]
+  },
+  "applicationId": "ce75a6b8-d72f-4b94-b09e-af6be35bc2ae"
+}
+```
+
+Abhängig von den Rahmenbedingungen können die weiteren Felder, die im Antragsmetadatenschema definiert sind, befüllt werden und mitversendet werden. Ob diese jedoch ausgewertet werden oder nicht hängt von dem entsprechenden Empfänger ab.
+
+### Verschlüsseln
+
+Nun wird das JSON-Objekt aus dem vorherigen Schritt verschlüsselt und kann dann im nächsten Schritt mit dem Antrag abgesendet werden.
+Die Verschlüsselung eines Objektes mit Hilfe von JWE ist im Bereich "[Verschlüsselte Übertragung](#overview--verschlüsselte-übertragung)" genauer beschrieben und kann dort nachgelesen werden.
+
+### Versenden des Antrags
+
+Sobald alle Anhänge eines Antrags hochgeladen sind, kann der Antrag abgesendet werden. Hierfür müssen die verschlüsselten Metadaten und, falls angekündigt, die Fachdaten über eine HTTP POST Nachricht gesendet werden. Ein Beispiel hierfür ist im folgenden Ausschnitt aufgezeigt:
+
+```text
+curl --data '{ "encryptedMetadata": "<jose-String>" }' -H 'Content-Type: application/json' -H 'X-AnwenderId: <Id>' -X POST <URL>/applications/<UUID>
+```
+
+```text
+curl --data '{ "encryptedMetadata": "eyJhbGciOiAiUlNBLU9BRVAiLCAiZW5jIjogIkExMjhDQkMtSFMyNTYifQ.SsLgP2bNKYDYGzHvLYY7rsVEBHSms6_jW-WfglHqD9giJhWwrOwqLZOaoOycsf_EBJCkHq9-vbxRb7WiNdy_C9J0_RnRRBGII6z_G4bVb18bkbJMeZMV6vpUut_iuRWoct_weg_VZ3iR2xMbl-yE8Hnc63pAGJcIwngfZ3sMX8rBeni_koxCc88LhioP8zRQxNkoNpvw-kTCz0xv6SU_zL8p79_-_2zilVyMt76Pc7WV46iI3EWIvP6SG04sguaTzrDXCLp6ykLGaXB7NRFJ5PJ9Lmh5yinAJzCdWQ-4XKKkNPorSiVmRiRSQ4z0S2eo2LtvqJhXCrghKpBNgbtnJQ.Awelp3ryBVpdFhRckQ-KKw.1MyZ-3nky1EFO4UgTB-9C2EHpYh1Z-ij0RbiuuMez70nIH7uqL9hlhskutO0oPjqdpmNc9glSmO9pheMH2DVag.Xccck85XZMvG-fAJ6oDnAw" }' -H 'Content-Type: application/json' -H 'X-AnwenderId: sender' -X POST localhost:8080/applications/9d618546-0ff7-4e93-9f15-714e5dd1bf12
+> {
+  "destinationId": "7a2668ad-3081-407c-9358-7ce4b6144b02",
+  "applicationId": "9d618546-0ff7-4e93-9f15-714e5dd1bf12",
+  "attachments": [],
+  "currentStatus": "forwarded",
+  "encryptedMetadata": "eyJhbGciOiAiUlNBLU9BRVAiLCAiZW5jIjogIkExMjhDQkMtSFMyNTYifQ.SsLgP2bNKYDYGzHvLYY7rsVEBHSms6_jW-WfglHqD9giJhWwrOwqLZOaoOycsf_EBJCkHq9-vbxRb7WiNdy_C9J0_RnRRBGII6z_G4bVb18bkbJMeZMV6vpUut_iuRWoct_weg_VZ3iR2xMbl-yE8Hnc63pAGJcIwngfZ3sMX8rBeni_koxCc88LhioP8zRQxNkoNpvw-kTCz0xv6SU_zL8p79_-_2zilVyMt76Pc7WV46iI3EWIvP6SG04sguaTzrDXCLp6ykLGaXB7NRFJ5PJ9Lmh5yinAJzCdWQ-4XKKkNPorSiVmRiRSQ4z0S2eo2LtvqJhXCrghKpBNgbtnJQ.Awelp3ryBVpdFhRckQ-KKw.1MyZ-3nky1EFO4UgTB-9C2EHpYh1Z-ij0RbiuuMez70nIH7uqL9hlhskutO0oPjqdpmNc9glSmO9pheMH2DVag.Xccck85XZMvG-fAJ6oDnAw",
+  "encryptedData": null,
+  "statusHistory": [
+    {
+      "sourceState": "queued",
+      "targetState": "forwarded",
+      "details": "Callback von Destination 7a2668ad-3081-407c-9358-7ce4b6144b02 ausgelöst.",
+      "timestamp": "2021-05-26T09:12:59.68968+02:00"
+    },
+    {
+      "sourceState": "incomplete",
+      "targetState": "queued",
+      "details": "Antrag versendet durch sender",
+      "timestamp": "2021-05-26T09:12:58.728397+02:00"
+    }
+  ],
+  "announcedContentStructure": {
+    "data": false,
+    "attachments": []
+  }
+}
+```
+
+## Prozess: Empfangen und verarbeiten eines Antrags
+
+### Abfragen des Antrags
+
+Wenn ein neuer Antrag bereitsteht, kann dieser über mehrere Befehle heruntergeladen werden. Mehrere dahingehend, da erst alle allgemeinen Informationen zum Antrag heruntergeladen werden müssen und dann, falls notwendig alle mit ihm verbundenen Anhänge.
+
+```text
+curl -H 'X-AnwenderId: <Id>' -X GET <URL>/applications/<UUID>
+
+# Falls ein Antrag noch entsprechend Anhänge besitzt, können diese über folgenden Befehl heruntergeladen werden:
+curl -H 'X-AnwenderId: <Id>' -X GET <URL>/applications/<UUID>/attachments/<UUID>
+```
+
+```text
+curl -H 'X-AnwenderId: subscriber' -X GET localhost:8080/applications/9d618546-0ff7-4e93-9f15-714e5dd1bf12
+> {
+  "destinationId": "7a2668ad-3081-407c-9358-7ce4b6144b02",
+  "applicationId": "9d618546-0ff7-4e93-9f15-714e5dd1bf12",
+  "attachments": [],
+  "currentStatus": "forwarded",
+  "encryptedMetadata": "eyJhbGciOiAiUlNBLU9BRVAiLCAiZW5jIjogIkExMjhDQkMtSFMyNTYifQ.SsLgP2bNKYDYGzHvLYY7rsVEBHSms6_jW-WfglHqD9giJhWwrOwqLZOaoOycsf_EBJCkHq9-vbxRb7WiNdy_C9J0_RnRRBGII6z_G4bVb18bkbJMeZMV6vpUut_iuRWoct_weg_VZ3iR2xMbl-yE8Hnc63pAGJcIwngfZ3sMX8rBeni_koxCc88LhioP8zRQxNkoNpvw-kTCz0xv6SU_zL8p79_-_2zilVyMt76Pc7WV46iI3EWIvP6SG04sguaTzrDXCLp6ykLGaXB7NRFJ5PJ9Lmh5yinAJzCdWQ-4XKKkNPorSiVmRiRSQ4z0S2eo2LtvqJhXCrghKpBNgbtnJQ.Awelp3ryBVpdFhRckQ-KKw.1MyZ-3nky1EFO4UgTB-9C2EHpYh1Z-ij0RbiuuMez70nIH7uqL9hlhskutO0oPjqdpmNc9glSmO9pheMH2DVag.Xccck85XZMvG-fAJ6oDnAw",
+  "encryptedData": null,
+  "statusHistory": [
+    {
+      "sourceState": "queued",
+      "targetState": "forwarded",
+      "details": "Callback von Destination 7a2668ad-3081-407c-9358-7ce4b6144b02 ausgelöst.",
+      "timestamp": "2021-05-26T09:12:59.68968+02:00"
+    },
+    {
+      "sourceState": "incomplete",
+      "targetState": "queued",
+      "details": "Antrag versendet durch sender",
+      "timestamp": "2021-05-26T09:12:58.728397+02:00"
+    }
+  ],
+  "announcedContentStructure": {
+    "data": false,
+    "attachments": []
+  }
+}
+```
+
+### Entschlüsseln
+
+Um den Antrag korrekt verarbeiten und überprüfen zu können müssen zuerst alle verschlüsselten Informationen entschlüsselt werden. Darunter fallen beispielsweise die Antragsmetadaten, die Fachdaten (falls vorhanden) oder Dokumente (falls vorhanden).
+
+Die Entschlüsselung eines solchen Objektes mit Hilfe von JWE ist im Bereich "[Verschlüsselte Übertragung](#overview--verschlüsselte-übertragung)" genauer beschrieben und kann dort nachgelesen werden.
+
+### Validierung der Antragsmetadaten
+
+Das Minimum, was an Information vorhanden sein muss sind die Felder `contentStructure` und `applicationId`. Zustäzlich können je nach Anwendungsfall oder Notwendigkeit weitere Felder auf Existenz überprüft werden. Die gültigen Formate sind im Schema definiert und können mit Hilfe von Bibliotheken für die Validierung einer Instanz von Antragsmetadaten verwendet werden. Beispiele für die Definition von Formaten für Felder sind unten aufgeführt.
+
+```json
+{
+  ...
+  "country": {
+    "type": "string",
+    "description": "Staat gemäß Codeliste [https://www.xrepository.de/details/urn:de:bund:destatis:bevoelkerungsstatistik:schluessel:staat](Codeliste Staat aus der Staats- und Gebietssystematik des Statistischen Bundesamtes)",
+    "minLength": 3,
+    "maxLength": 3,
+    "pattern": "^[0-9]{3}$"
+  },
+  ...
+  "postalCode": {
+    "type": "string",
+    "description": "Postleitzahl",
+    "minLength": 5,
+    "maxLength": 5,
+    "pattern": "^([0]{1}[1-9]{1}|[1-9]{1}[0-9]{1})[0-9]{3}$"
+  },
+  ...
+  "applicationId": {
+    "type": "string",
+    "format": "uuid",
+    "pattern": "^[-_.A-Za-z0-9]+$",
+    "description": "ID des Antrags"
+  },
+  ...
+}
+```
+
+### Verarbeiten des Antrags
+
+Nachdem nun der Antrag vollständig heruntergeladen wurde und validiert wurde, sollte dieser entsprechend bestätigt werden. Dies muss über ein HTTP PUT, wie unten aufgezeigt, durchgeführt werden.
+
+```text
+curl -H 'X-AnwenderId: <Id>' -X PUT <URL>/applications/<UUID>
+```
+
+```text
+curl -H 'X-AnwenderId: subscriber' -X PUT localhost:8080/applications/9d618546-0ff7-4e93-9f15-714e5dd1bf12
+> {}
+```

docs/_Overview.md

@@ -4,37 +4,41 @@ Willkommen auf der API Dokumentation für die XFall REST API von FIT-Connect. Di
 
 ## Was ist die XFall API und was unterscheidet diese API vom bisherigen XFall Standard?
 
-Die XFall API baut auf den bisherigen Konzepten und Erfahrungen des bestehenden IT-Planungsrats Standards XFall auf. 
+Die XFall API baut auf den bisherigen Konzepten und Erfahrungen des bestehenden IT-Planungsrats Standards XFall auf.
 
-> Die übergreifende Zielstellung des Standards XFall besteht darin, Anträge und Berichte, die aus vorgelagerten Systemen (bspw. Onlineantragsdienste, Fachportale oder Berichtssysteme) erstellt werden, in die unterschiedlichen Systeme der elektronischen Verfahrensbearbeitung (bspw. Fachverfahren, Dokumentenmanagementsystem oder Prozessplattformen) zu übergeben. 
+> Die übergreifende Zielstellung des Standards XFall besteht darin, Anträge und Berichte, die aus vorgelagerten Systemen (bspw. Onlineantragsdienste, Fachportale oder Berichtssysteme) erstellt werden, in die unterschiedlichen Systeme der elektronischen Verfahrensbearbeitung (bspw. Fachverfahren, Dokumentenmanagementsystem oder Prozessplattformen) zu übergeben.
 
 Bei der Entwicklung der XFall API wurden viele Konzepte mit Hinblick auf die neuen Erfordernisse des Onlinezugangsgesetzes, der SDG-Verordnung sowie den Anforderungen digitaler Geschäftsmodelle weiterentwickelt. Technisch nutzt die XFall API auf einen leichtgewichtigen RESTful-Architekturstil und baut auf der föderalen Antragsübertragungsarchitektur von FIT-Connect auf.
 
 ## Was macht die XFall API und wie kann diese genutzt werden?
 
 Die XFall API besteht aus zwei getrennt nutzbaren APIs:
-- Für antragsempfangende Systeme wird eine `Application Subscriber API` für den Empfang von Anträgen sowie eine `Callback` / Webhook Funktion für die technische Benachrichtigung über vorliegende Anträge angeboten. 
+
+- Für antragsempfangende Systeme wird eine `Application Subscriber API` für den Empfang von Anträgen sowie eine `Callback` / Webhook Funktion für die technische Benachrichtigung über vorliegende Anträge angeboten.
 - Für antragssendende Systeme wird eine `Application Sender API` angeboten, um an beliebige antragsempfangende Systeme Anträge zu senden, die sich mit einem Zustellpunkt registriert haben.
 
 Diese beiden APIs werden durch einen zentralen Intermediär (`XFall Zustelldienst`) bereitgestellt. Um auf diese APIs zuzugreifen, müssen interessierte Entwickler ihre Anwendungen beim FIT-Connect Autorisierungsdienst vorab registrieren.
 
 ### Zusammenspiel der APIs in der Antragsübermittlung
+
 ![Applicationtransfer_Architecture](../assets/images/api_overview/XFall_Integration_Architecture.png "Antragsübertragungsarchitektur FIT-Connect")
 
 Über die `Application Subscriber API` können die zuständigen Stellen für ihre Systeme einen Zustellpunkt eröffnen, der über eine `destination-Id` eindeutig adressierbar ist. Für diese Zustellpunkte legen die zuständigen Stellen alle fachlichen Vorgaben (Zulässige Fachstandards, Verschlüsselung, Datenformate etc.) fest, damit eine medienbruchfreie Weiterverarbeitung in ihren Systemen gewährleistet ist. Über die Angabe der `destination-Id` in der `Application Sender API` können beliebige antragssendende Systemen Anträge an die zuständige Stelle senden.
 
-Dieser Zustellpunkt ist jedoch vorab für eine Verwaltungsleistung und den jeweiligen örtlichen Antragskontext (bspw. Ort der Antragsstellung) korrekt zu ermitteln. Damit die Ermittlung des korrekten Zustellpunkts skalierbar für das ganze Bundesgebiet funktioniert, ist langfristig vorgesehen, die `destination-Id` in den Leistungs- und Zuständigkeitsinformationen des jeweils bekannten Zuständigkeitsfinders zu hinterlegen. Diese dezentral gepflegten Informationen sollen durch das Online-Gateway (https://www.onlinezugangsgesetz.de/Webs/OZG/DE/umsetzung/portalverbund/online-gateway/online-gateway-node.html) gebündelt und über eine offene API im XZuFi Format (https://www.xrepository.de/details/urn:xoev-de:fim:standard:xzufi) nutzbar gemacht werden.
+Dieser Zustellpunkt ist jedoch vorab für eine Verwaltungsleistung und den jeweiligen örtlichen Antragskontext (bspw. Ort der Antragsstellung) korrekt zu ermitteln. Damit die Ermittlung des korrekten Zustellpunkts skalierbar für das ganze Bundesgebiet funktioniert, ist langfristig vorgesehen, die `destination-Id` in den Leistungs- und Zuständigkeitsinformationen des jeweils bekannten Zuständigkeitsfinders zu hinterlegen. Diese dezentral gepflegten Informationen sollen durch das Online-Gateway (<https://www.onlinezugangsgesetz.de/Webs/OZG/DE/umsetzung/portalverbund/online-gateway/online-gateway-node.html>) gebündelt und über eine offene API im XZuFi Format (<https://www.xrepository.de/details/urn:xoev-de:fim:standard:xzufi>) nutzbar gemacht werden.
 
 ![Applicationtransfer_Architecture](https://raw.githubusercontent.com/fiep-poc/assets/master/images/api_overview/Pflege%20und%20Ermittlung%20destination-Id.jpg "Pflege und Ermittlung der destination-Id")
 
 ## Für wen ist die XFall API gedacht und warum sollte ich sie nutzen?
 
 Die XFall API ist für alle Hersteller, Entwickler und Verfahrensverantwortliche von antragssendenden und antragsempfangenden Systemen gedacht. Insbesondere folgende Systeme mit bundesweiten Nutzungsszenarien sollen mit der XFall API unterstützt werden:
+
 - **Einer für alle (EfA) Verfahren**: Länderübergreifend entwickelte Antragsverfahren für eine bestimmte Verwaltungsleistung oder ein Leistungsbündel, die entweder in verschiedenen Ländern nachnutzbar betrieben werden oder länderübergreifend als gemeinsamer Antragsdienst für alle zuständigen Stellen betrieben werden.
 - **Antragsgeneratoren / Antragsmanagementsysteme**: Standardsoftware zur Erstellung und dem Betrieb von direkt nutzbaren Onlineantragsdiensten, die im ganzen Bundesgebiet bei einzelnen Stellen oder Gebietskörperschaften (bspw. als Basiskomponente) im Einsatz sind.
 - **Als Standardsoftware bereitgestellte Fachverfahrenssoftware, Prozessplattformen oder Dokumentenmanagementsysteme**: Bundesweit angebotene und eingesetzte Standardsoftware, die von den zuständigen Stellen für die Antragsbearbeitung eingesetzt wird.
 
-Für diese Systeme bietet die XFall bei der schnellen und wirtschaftlichen Realisierung medienbruchfreier Antragsprozesse eine Reihe von Mehrwerten: 
+Für diese Systeme bietet die XFall bei der schnellen und wirtschaftlichen Realisierung medienbruchfreier Antragsprozesse eine Reihe von Mehrwerten:
+
 - **Plug and Play Anbindung an die föderale Antragsübermittlung**: Durch die zentral bereitgestellten APIs und die Nutzung der bestehenden Zuständigkeitsfinderinfrastruktur können Systeme schnell an eine föderale Antragsübermittlungsinfrastruktur angebunden werden, ohne eigene Infrastrukturen hierfür zu beauftragen oder aufzubauen.
 - **Leichgewichtige APIs und Industriestandards**: Die XFall API baut auf leichgewichtigen RESTful API Ansätzen auf und nutzt verbreitete Industriestandards wie die OpenAPI Specification und OAuth 2.0, sodass kein spezialisiertes Know-How und spezifische Softwarekomponenten für die Anbindung erforderlich sind.
 - **Flexibilität in der Antragsübermittlung**: Die XFall API verbindet Flexibilität und Standardisierung. Während die XFall API eine einheitliche Metadatenstruktur festlegt, um Anträge strukturiert zu verarbeiten, können beliebige Fachstandards und Anhänge übertragen werden. Auch die Übertragung von Anträgen im PDF Format ist möglich, solange für die Antragsdaten noch kein FIM Schema vorhanden ist.

metadata-schema/antragsmetadaten.schema.json

+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://fitko.uber.space/API_VERSION/antragsmetadaten.schema.json",
+  "type": "object",
+  "title": "Antragsmetadaten",
+  "description": "",
+  "properties": {
+    "applicationId": {
+      "type": "string",
+      "format": "uuid",
+      "pattern": "^[-_.A-Za-z0-9]+$",
+      "description": "ID des Antrags"
+    },
+    "applicants": {
+      "type": "array",
+      "items": {
+        "title": "Applicant",
+        "description": "Ein Antragsteller, entweder eine Organisation oder eine natürliche Person",
+        "type": "object",
+        "oneOf": [
+          {
+            "$ref": "#/definitions/Applicant-person"
+          },
+          {
+            "$ref": "#/definitions/Applicant-organization"
+          }
+        ],
+        "discriminator": {
+          "propertyName": "type",
+          "mapping": {
+            "person": "#/definitions/Applicant-person",
+            "organization": "#/definitions/Applicant-organization"
+          }
+        }
+      }
+    },
+    "paymentInfo": {
+      "$ref": "#/definitions/Payment-info"
+    },
+    "publicServiceType": {
+      "$ref": "#/definitions/Public-service-type"
+    },
+    "contentStructure": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "docs"
+      ],
+      "properties": {
+        "data": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "schema": {
+              "$ref": "#/definitions/Schema"
+            }
+          },
+          "required": [
+            "schema"
+          ]
+        },
+        "docs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/Document"
+          }
+        }
+      }
+    },
+    "additionalReferenceInfo": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "subject": {
+          "type": "string"
+        },
+        "caseId": {
+          "type": "string"
+        },
+        "applicationDate": {
+          "type": "string",
+          "format": "date",
+          "description": "Antragsdatum"
+        }
+      }
+    }
+  },
+  "required": [
+    "contentStructure"
+  ],
+  "definitions": {
+    "Applicant-contact-info": {
+      "type": "object",
+      "title": "Applicant Contact Info",
+      "description": "Kontaktdaten des Antragstellers",
+      "additionalProperties": false,
+      "x-examples": {
+        "example-1": {
+          "electronicAdresses": [
+            {
+              "channelType": "Service-Account-Mailbox",
+              "address": "3b0c9c8c-0801-45f0-a331-2abfc9db78d0"
+            }
+          ],
+          "physicalAdress": {
+            "street": "Kurzer Weg",
+            "houseNumber": "7",
+            "postalCode": "12345",
+            "city": "Ankh-Morpork"
+          },
+          "telephones": [
+            {
+              "number": "+49 89 32168-42",
+              "mobile": true,
+              "description": "work"
+            }
+          ]
+        }
+      },
+      "properties": {
+        "physicalAddress": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/Address-national"
+            },
+            {
+              "$ref": "#/definitions/Address-postbox"
+            },
+            {
+              "$ref": "#/definitions/Address-international"
+            }
+          ],
+          "description": "Physikalische (Post-)Adresse",
+          "discriminator": {
+            "propertyName": "type",
+            "mapping": {
+              "national": "#/definitions/Address-national",
+              "postbox": "#/definitions/Address-postbox",
+              "international": "#/definitions/Address-international"
+            }
+          }
+        },
+        "telephones": {
+          "type": "array",
+          "description": "Liste der Telefonnummern, außer Fax",
+          "items": {
+            "$ref": "#/definitions/Phone"
+          }
+        },
+        "electronicAddresses": {
+          "type": "array",
+          "description": "Elektronische Kontaktmöglkichkeiten, z.B. E-Mail",
+          "items": {
+            "type": "object",
+            "description": "",
+            "additionalProperties": false,
+            "properties": {
+              "channelType": {
+                "type": "string",
+                "enum": [
+                  "Service-Account-Mailbox",
+                  "De-Mail",
+                  "E-Mail",
+                  "Fax"
+                ],
+                "description": "Art der Kommunikationsmöglichkeit"
+              },
+              "address": {
+                "type": "string",
+                "description": "Kommunikationsadresse"
+              }
+            }
+          }
+        }
+      }
+    },
+    "Applicant-organization": {
+      "type": "object",
+      "title": "Applicant Organisation",
+      "description": "Antragsteller in Form von einer Organisation, z.B. einem Unternehmen",
+      "additionalProperties": false,
+      "properties": {
+        "identifier": {
+          "type": "array",
+          "description": "IDs für diese Organisation",
+          "items": {
+            "$ref": "#/definitions/Identifier"
+          }
+        },
+        "contactInfo": {
+          "$ref": "#/definitions/Applicant-contact-info"
+        },
+        "actingPerson": {
+          "type": "array",
+          "description": "Im Namen der Organisation auftretende natürliche Personen, wie z.B. Geschäftsführer, Vorstände oder Prokuristen",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "identityInfo": {
+                "$ref": "#/definitions/Natural-person"
+              },
+              "authentificationInfo": {
+                "$ref": "#/definitions/Authentification-info"
+              }
+            }
+          }
+        },
+        "organizationInfo": {
+          "type": "object",
+          "description": "Informationen über die Organisation",
+          "additionalProperties": false,
+          "properties": {
+            "legalName": {
+              "type": "string",
+              "description": "Name oder Bezeichnung - Der rechtliche Name einer Organisation. Der Name ist nicht zwingend eindeutig, um die Organisation zu identifizieren."
+            },
+            "organizationType": {
+              "type": "string",
+              "description": "Rechtsform der Organisation"
+            },
+            "registryCourt": {
+              "type": "string",
+              "description": "Registergericht"
+            },
+            "registryType": {
+              "type": "string",
+              "description": "Registerart - Die Registerart macht die Registernummer zur Identifizierung der Organisation innerhalb des Registergerichts eindeutig (z. B. HRA und HRB als Registerarten für das Handelsregister)."
+            },
+            "registryNumber": {
+              "type": "string",
+              "description": "Registernummer, z.B. vom Handelsregister"
+            },
+            "legalAddress": {
+              "oneOf": [
+                {
+                  "$ref": "#/definitions/Address-national"
+                },
+                {
+                  "$ref": "#/definitions/Address-postbox"
+                },
+                {
+                  "$ref": "#/definitions/Address-international"
+                }
+              ],
+              "description": "Offizielle Adresse",
+              "discriminator": {
+                "propertyName": "type",
+                "mapping": {
+                  "national": "#/definitions/Address-national",
+                  "postbox": "#/definitions/Address-postbox",
+                  "international": "#/definitions/Address-international"
+                }
+              }
+            },
+            "legalRepresentatives": {
+              "type": "array",
+              "description": "Namen der Mitglieder des Vertretungsorgans oder der gesetzlichen Vertreter",
+              "items": {
+                "$ref": "#/definitions/Individual"
+              }
+            }
+          }
+        },
+        "orgValidation": {
+          "type": "object",
+          "description": "Informationen, ob diese Organisation vom sendenden System identifiziert wurde",
+          "additionalProperties": false,
+          "properties": {
+            "method": {
+              "type": "string",
+              "description": "Identifizierungsmethode"
+            }
+          },
+          "required": [
+            "method"
+          ]
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "organization"
+          ]
+        }
+      },
+      "required": [
+        "type"
+      ]
+    },
+    "Applicant-person": {
+      "type": "object",
+      "title": "Applicant Person",
+      "description": "Antragstellerdaten für eine natürliche Person",
+      "additionalProperties": false,
+      "properties": {
+        "identifier": {
+          "type": "array",
+          "description": "IDs der natürlichen Person",
+          "items": {
+            "$ref": "#/definitions/Identifier"
+          }
+        },
+        "authentificationInfo": {
+          "$ref": "#/definitions/Authentification-info"
+        },
+        "identityInfo": {
+          "$ref": "#/definitions/Natural-person"
+        },
+        "contactInfo": {
+          "$ref": "#/definitions/Applicant-contact-info"
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "person"
+          ]
+        }
+      },
+      "required": [
+        "type"
+      ]
+    },
+    "Document": {
+      "type": "object",
+      "title": "Application Document",
+      "description": "Ein im Antrag (Application) enthaltenes Dokument (z.B. Antragsformular oder hochgeladene Anlage)",
+      "additionalProperties": false,
+      "properties": {
+        "purpose": {
+          "type": "string",
+          "enum": [
+            "form",
+            "attachment",
+            "report"
+          ],
+          "description": "Zweck/Art des Dokuments\n- form: Antragsformular\n- attachment: Anlage (Upload)\n- report: Vom System erzeugte Unterlage"
+        },
+        "size": {
+          "type": "integer",
+          "description": "Größe des Dokuments in Bytes"
+        },
+        "filename": {
+          "type": "string",
+          "description": "Ursprünglicher Dateiname bei Erzeugung oder Upload"
+        },
+        "description": {
+          "type": "string",
+          "description": "Optionale Beschreibung des Dokuments"
+        },
+        "lang": {
+          "$ref": "#/definitions/Language"
+        },
+        "hash": {
+          "type": "object",
+          "description": "Prüfsumme über den Inhalt des Dokuments zur Absicherung auf dem Transportweg",
+          "additionalProperties": false,
+          "properties": {
+            "algorithm": {
+              "type": "string",
+              "description": "Verwendeter Algorithmus",
+              "enum": [
+                "SHA-256",
+                "SHA-512"
+              ]
+            },
+            "digest": {
+              "type": "string",
+              "description": "Prüfsumme, hexadezimal codiert",
+              "pattern": "^[A-Fa-f0-9]{64}([A-Fa-f0-9]{64})?$"
+            }
+          },
+          "required": [
+            "algorithm",
+            "digest"
+          ]
+        },
+        "signature": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9-_=]+$",
+          "description": "Sofern der Antragstellers dieses Dokument signiert hat, wird die Signatur hier base64url-encoded eingebettet"
+        },
+        "mimeType": {
+          "$ref": "#/definitions/Mime-type"
+        },
+        "docId": {
+          "type": "string",
+          "pattern": "^[-_.A-Za-z0-9]+$",
+          "description": "ID des Dokuments. Diese muss nur innerhalb des Antrags (Application) eindeutig sein. Es wird daher empfohlen, die IDs fortlaufend (1, 2 etc.) zu vergeben."
+        }
+      },
+      "required": [
+        "purpose",
+        "size",
+        "mimeType"
+      ]
+    },
+    "Payment-info": {
+      "type": "object",
+      "title": "Payment Info",
+      "description": "Informationen über eine im Antragsprozess erfolgte Bezahlung.",
+      "additionalProperties": false,
+      "properties": {
+        "reference": {
+          "type": "string",
+          "description": "Bezahlreferenz, z.B. ein Kassenzeichen"
+        },
+        "usage": {
+          "type": "string",
+          "description": "Verwendungszweck",
+          "maxLength": 27
+        },
+        "amount": {
+          "type": "number",
+          "minimum": 0.01,
+          "multipleOf": 0.01,
+          "description": "Geldbetrag"
+        },
+        "timestamp": {
+          "type": "string",
+          "description": "Zeitpunkt der Bezahlung",
+          "format": "date-time"
+        },
+        "status": {
+          "type": "string",
+          "description": "Status der Bezahlung",
+          "enum": [
+            "success",
+            "failed",
+            "open"
+          ]
+        },
+        "transaction": {
+          "type": "string",
+          "description": "Informationen zur Bezahltransaktion, z.B. eine Transaktions-ID"
+        }
+      },
+      "required": [
+        "usage",
+        "amount",
+        "status"
+      ],
+      "x-examples": {
+        "example-1": {
+          "reference": "TP/93/GDP",
+          "usage": "Gewerbeanmeldung",
+          "amount": 17.3,
+          "timestamp": "2020-03-03T12:38:23Z",
+          "status": "success",
+          "transaction": "1f77c5f9b759db9cdce59988b24974d465c7be5e462a6185485559ff6e2dea82"
+        }
+      }
+    },
+    "Public-service-type": {
+      "type": "object",
+      "title": "Verwaltungsleistung",
+      "description": "Beschreibung der Art der Verwaltungsleistung. Eine Verwaltungleistung sollte immer mit einer LeiKa-ID beschrieben werden. Ist für die gegebene Verwaltungsleistung keine LeiKa-ID vorhanden, kann die Verwaltungsleistung übergangsweise über die Angabe eines Schemas (`otherIdentifiers`) beschrieben werden.",
+      "additionalProperties": false,
+      "x-examples": {
+        "example-1": {
+          "name": "Gewerbeanmeldung",
+          "description": "Eine Gewerbeanmeldung ist immer dann notwendig, wenn Sie einen stehenden Gewerbebetrieb beginnen.",
+          "leikaId": "99050012104000",
+          "otherIdentifiers": [
+            {
+              "id": "8664844",
+              "schemaID": "service.niedersachsen.de",
+              "schemaName": "Serviceportal Niedersachsen"
+            },
+            {
+              "id": "354824",
+              "schemaID": "buerger.thueringen.de",
+              "schemaName": "Zuständigkeitsfinder Thüringen"
+            }
+          ]
+        },
+        "example-2": {
+          "name": "Gewerbeanmeldung",
+          "leikaId": "99050012104000"
+        }
+      },
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Name/Bezeichnung der behördlichen Leistung"
+        },
+        "description": {
+          "type": "string",
+          "description": "(Kurz-)Beschreibung der behördlichen Leistung"
+        },
+        "otherIdentifiers": {
+          "type": "array",
+          "description": "Weitere Identifikatioren. Die ID wird in `content` abgelegt, zusätzlich sollten die Schema-Attribute zur Spezifikation des Gültigkeitsraumes verwendet werden.",
+          "items": {
+            "$ref": "#/definitions/Identifier"
+          }
+        },
+        "leikaId": {
+          "type": "string",
+          "pattern": "^[0-9]{2}([0-9]{3}){1,4}$",
+          "description": "ID aus dem Leistungskatalog (Leika)"
+        },
+        "legalBasis": {
+          "type": "string",
+          "description": "Rechtsgrundlage der Verwaltungsleistung. Dieses Feld dient zur Information für Verwaltungsmitarbeiter:innen und stellt insbesondere keine rechtsverbindliche Aussage dar."
+        }
+      },
+      "required": [
+        "name"
+      ]
+    },
+    "Schema": {
+      "type": "object",
+      "title": "Application Schema",
+      "description": "Strukturinformationen zu übertragbaren oder übertragenen Daten.",
+      "additionalProperties": false,
+      "x-examples": {
+        "example-1": {
+          "mimeType": "application/json",
+          "schemaSource": "none"
+        },
+        "example-2": {
+          "mimeType": "application/xml",
+          "schemaSource": "none"
+        },
+        "example-3": {
+          "mimeType": "application/xml",
+          "schemaSource": "fim",
+          "schemaId": "S99000001V1.0"
+        }
+      },
+      "properties": {
+        "schemaId": {
+          "type": "string",
+          "description": "ID des Schemas, abhängig von der ausgewählten Quelle."
+        },
+        "schemaSource": {
+          "type": "string",
+          "enum": [
+            "fim",
+            "none"
+          ],
+          "description": "Quelle, von der das Schema bezogen werden kann."
+        },
+        "mimeType": {
+          "type": "string",
+          "enum": [
+            "application/json",
+            "application/xml"
+          ],
+          "description": "Gibt das zulässige Format (JSON oder XML) der Fachdaten an."
+        },
+        "encoding": {
+          "type": "string",
+          "enum": [
+            "plain",
+            "base64",
+            "jwe"
+          ],
+          "description": "Übertragungscodierung:\n- `plain`: kein Encoding\n- `base64`: Inhalt base64-codieren\n- `jwe`: Inhalt mit JSON Web Encryption verschlüsseln"
+        }
+      },
+      "required": [
+        "schemaSource",
+        "mimeType",
+        "encoding"
+      ]
+    },
+    "Address-international": {
+      "type": "object",
+      "title": "International Address",
+      "description": "Eine internationale Adresse, bestehend aus ein bis fünf Adresszeilen.",
+      "additionalProperties": false,
+      "x-examples": {
+        "example-1": {
+          "type": "international",
+          "lines": [
+            "760 United Nations Plaza",
+            "Manhattan, New York City, New York 10017"
+          ],
+          "country": "368"
+        },
+        "example-2": {
+          "type": "international",
+          "lines": [
+            "Threadneedle Street",
+            "London EC2R 8AH"
+          ],
+          "country": "168"
+        }
+      },
+      "properties": {
+        "lines": {
+          "type": "array",
+          "maxItems": 5,
+          "minItems": 2,
+          "description": "Anschriftzeile",
+          "items": {
+            "type": "string",
+            "maxLength": 35
+          }
+        },
+        "country": {
+          "type": "string",
+          "description": "Staat gemäß Codeliste [https://www.xrepository.de/details/urn:de:bund:destatis:bevoelkerungsstatistik:schluessel:staat](Codeliste Staat aus der Staats- und Gebietssystematik des Statistischen Bundesamtes)",
+          "minLength": 3,
+          "maxLength": 3,
+          "pattern": "^[0-9]{3}$"
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "international"
+          ]
+        }
+      },
+      "required": [
+        "lines",
+        "country",
+        "type"
+      ]
+    },
+    "Address-national": {
+      "title": "National Address",
+      "description": "Eine nationale (deutsche) Adresse, bestehend aus Straße, Hausnummer, PLZ und Ort.",
+      "x-examples": {
+        "example-1": {
+          "type": "national",
+          "street": "Kurzer Weg",
+          "houseNumber": "7",
+          "postalCode": "12345",
+          "city": "Ankh-Morpork"
+        }
+      },
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "street": {
+          "type": "string",
+          "description": "Straße",
+          "maxLength": 55
+        },
+        "houseNumber": {
+          "type": "string",
+          "description": "Hausnummer",
+          "maxLength": 9,
+          "pattern": "^[1-9][0-9]{0,3}(-[1-9][0-9]{0,3})?$"
+        },
+        "houseNumberSuffix": {
+          "type": "string",
+          "description": "Hausnummerzusatz",
+          "maxLength": 2,
+          "pattern": "^[A-Za-z0-9. ]*$"
+        },
+        "postalCode": {
+          "type": "string",
+          "description": "Postleitzahl",
+          "minLength": 5,
+          "maxLength": 5,
+          "pattern": "^([0]{1}[1-9]{1}|[1-9]{1}[0-9]{1})[0-9]{3}$"
+        },
+        "city": {
+          "type": "string",
+          "description": "Ort",
+          "maxLength": 50
+        },
+        "addressSupplement": {
+          "type": "string",
+          "description": "Adresszusatz"
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "national"
+          ]
+        }
+      },
+      "required": [
+        "street",
+        "postalCode",
+        "city",
+        "type"
+      ]
+    },
+    "Address-postbox": {
+      "title": "Postfach Address",
+      "description": "Eine Adresse eines Postfachs.",
+      "x-examples": {
+        "example-1": {
+          "type": "postbox",
+          "postOfficeBox": "987",
+          "postalCode": "12345",
+          "city": "Ankh-Morpork"
+        }
+      },
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "postOfficeBox": {
+          "type": "string",
+          "description": "Postfach"
+        },
+        "postalCode": {
+          "type": "string",
+          "description": "Postleitzahl",
+          "minLength": 5,
+          "maxLength": 5,
+          "pattern": "^([0]{1}[1-9]{1}|[1-9]{1}[0-9]{1})[0-9]{3}$"
+        },
+        "city": {
+          "type": "string",
+          "description": "Ort",
+          "maxLength": 50
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "postbox"
+          ]
+        }
+      },
+      "required": [
+        "postalCode",
+        "city",
+        "type"
+      ]
+    },
+    "Authentification-info": {
+      "type": "object",
+      "title": "Authentifikation",
+      "additionalProperties": false,
+      "description": "Informationen über die Authentifikation der Person.",
+      "x-examples": {
+        "example-1": {
+          "assuranceLevel": "high",
+          "authentificationMethod": "eID",
+          "timestamp": "2020-03-03T12:38:23Z"
+        }
+      },
+      "properties": {
+        "assuranceLevel": {
+          "type": "string",
+          "enum": [
+            "low",
+            "substantial",
+            "high"
+          ],
+          "description": "Vertrauensniveau"
+        },
+        "authentificationMethod": {
+          "type": "string",
+          "description": "Methode der Authentifikation",
+          "enum": [
+            "Authega",
+            "De-Mail",
+            "eID",
+            "E-Mail"
+          ]
+        },
+        "authentificationToken": {
+          "type": "object"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Zeitstempel der Authentifikation"
+        },
+        "authenticatedFields": {
+          "type": "array",
+          "minItems": 0,
+          "uniqueItems": true,
+          "description": "Liste der authentifizierten Felder in `identityInfo`",
+          "items": {
+            "type": "string",
+            "enum": [
+              "placeOfBirth",
+              "dateOfBirth",
+              "gender",
+              "nationality",
+              "artisticName",
+              "doctoralDegrees",
+              "birthName",
+              "givenName",
+              "familyName",
+              "placeOfResidence"
+            ]
+          }
+        }
+      },
+      "required": [
+        "assuranceLevel",
+        "authentificationMethod",
+        "authenticatedFields"
+      ]
+    },
+    "Identifier": {
+      "type": "object",
+      "title": "Identifier",
+      "description": "Identifiers are keys that are owned by either the sender, receiver or a third party. If the keys used are owned by either sender or receiver, no meta data has to be specified by means of attributes. The table below specifies the use of attributes for the identifier types when they are owned by a third party.",
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "A character string to identify and distinguish uniquely, one instance of an object in an identification schema from all other objects in the same schema together with relevant supplementary information."
+        },
+        "schemaURI": {
+          "type": "string",
+          "format": "uri",
+          "description": "Link to the location of the list schema"
+        },
+        "schemaDataURI": {
+          "type": "string",
+          "format": "uri",
+          "description": "Link to the location of the list"
+        },
+        "schemaVersionId": {
+          "type": "string",
+          "description": "Version of the schema"
+        },
+        "schemaAgencyName": {
+          "type": "string",
+          "description": "Specifies the name of the ID issuer"
+        },
+        "schemaAgencyId": {
+          "type": "string",
+          "description": "Specifies the ID of the ID issuer"
+        },
+        "schemaName": {
+          "type": "string",
+          "description": "Name of the schema"
+        },
+        "schemaId": {
+          "type": "string",
+          "description": "Identifices the ID type"
+        }
+      },
+      "required": [
+        "id"
+      ],
+      "x-examples": {
+        "example-1": {
+          "id": "8664844",
+          "schemaId": "service.niedersachsen.de",
+          "schemaName": "Serviceportal Niedersachsen"
+        }
+      }
+    },
+    "Individual": {
+      "type": "object",
+      "title": "Individual",
+      "description": "Natürliche Person",
+      "additionalProperties": false,
+      "x-examples": {
+        "example-1": {
+          "formOfAddress": "Herr",
+          "doctoralDegrees": "Dr.",
+          "firstName": "Kunibert",
+          "lastName": "Vonundzu",
+          "contact": {
+            "telephones": [
+              {
+                "number": "+49 89 32168-42",
+                "mobile": false,
+                "description": "work"
+              },
+              {
+                "number": "+49 123 456789",
+                "mobile": true,
+                "description": "work"
+              }
+            ],
+            "email": "kunibert.vonundzu@example.com"
+          }
+        }
+      },
+      "properties": {
+        "formOfAddress": {
+          "type": "string",
+          "description": "Anrede der Person wie \"Herr\" oder \"Frau\""
+        },
+        "doctoralDegrees": {
+          "type": "string",
+          "description": "Titel der Person wie \"Dr.\" oder \"Prof.\""
+        },
+        "firstName": {
+          "type": "string",
+          "description": "Vorname der Person"
+        },
+        "lastName": {
+          "type": "string",
+          "description": "Nachname der Person"
+        },
+        "address": {
+          "description": "Adresse als Alternative (Choice) von nationaler und internationaler Adresse.",
+          "oneOf": [
+            {
+              "$ref": "#/definitions/Address-national"
+            },
+            {
+              "$ref": "#/definitions/Address-postbox"
+            },
+            {
+              "$ref": "#/definitions/Address-international"
+            }
+          ],
+          "discriminator": {
+            "propertyName": "type",
+            "mapping": {
+              "national": "./address-national.json",
+              "postbox": "./address-postbox.json",
+              "international": "./address-international.json"
+            }
+          }
+        },
+        "identifiers": {
+          "type": "array",
+          "description": "Externe Identifikatoren der Person",
+          "items": {
+            "$ref": "#/definitions/Identifier"
+          }
+        },
+        "contact": {
+          "type": "object",
+          "description": "Kontaktmöglichkeiten einer Person (natürliche Person oder Organisation)",
+          "additionalProperties": false,
+          "properties": {
+            "telephones": {
+              "type": "array",
+              "description": "Liste der Telefonnummern, außer Fax",
+              "items": {
+                "$ref": "#/definitions/Phone"
+              }
+            },
+            "email": {
+              "type": "string",
+              "format": "email",
+              "description": "E-Mail-Adresse"
+            },
+            "www": {
+              "type": "string",
+              "format": "uri",
+              "description": "Webadresse"
+            },
+            "telefax": {
+              "$ref": "#/definitions/Phone/properties/number"
+            }
+          }
+        }
+      }
+    },
+    "Language": {
+      "type": "object",
+      "title": "Language",
+      "description": "Angaben zur Sprache basierend auf dem IETF language tag. Es wird jedoch nur ein Subset unterstützt:\n- `lang`: Die Primary Language darf nur aus zwei oder drei Kleinbuchstaben bestehen (gemäß  ISO 639-1 (2002), ISO 639-2 (1998), ISO 639-3 (2007) oder ISO 639-5 (2008))\n- `region`: Die Region muss aus zwei Großbuchstaben bestehen (gemäß ISO 3166-1 alpha-2)\n- `variant`: Sprachvariante (gemäß IANA Registry), derzeit wird nur `simple` unterstützt.",
+      "additionalProperties": false,
+      "properties": {
+        "lang": {
+          "type": "string",
+          "description": "primary language based on a two-letter language code from ISO 639-1 (2002) or a three-letter code from ISO 639-2 (1998), ISO 639-3 (2007) or ISO 639-5 (2008)",
+          "minLength": 2,
+          "maxLength": 3,
+          "pattern": "[a-z]{2,3}"
+        },
+        "region": {
+          "type": "string",
+          "description": "region based on a two-letter country code from ISO 3166-1 alpha-2",
+          "minLength": 2,
+          "maxLength": 2,
+          "pattern": "[A-Z]{2}"
+        },
+        "variant": {
+          "type": "string",
+          "enum": [
+            "simple"
+          ],
+          "description": "Subset der IANA language variant subtags\n- `simple`: Simplified form"
+        }
+      },
+      "required": [
+        "lang"
+      ],
+      "x-examples": {
+        "example-1": {
+          "lang": "de"
+        },
+        "example-2": {
+          "lang": "en",
+          "region": "GB"
+        },
+        "example-3": {
+          "lang": "de",
+          "region": "DE",
+          "variant": "simple"
+        }
+      }
+    },
+    "Mime-type": {
+      "type": "string",
+      "title": "MIME Type",
+      "description": "Internet Media Type gemäß RFC 2045, z.B. application/pdf.",
+      "example": "application/xml",
+      "pattern": "^[-\\w.]+/[-\\w.+]+$"
+    },
+    "Natural-person": {
+      "title": "Identity Information",
+      "description": "Informationen zu einer natürlichen Person. Wichtig: Wenn einzelne Felder für einen elektronischen Identitätsnachweis als Schriftform-Ersatz genutzt werden, MUSS geprüft werden, ob im Objekt `authentificationInfo` ein entsprechendes Authentifizierungslevel angegeben ist. Zusätzlich MUSS geprüft werden, ob die genutzten Felder im Object `authenticatedFields` enthalten sind.",
+      "type": "object",
+      "x-examples": {
+        "example-1": {
+          "dateOfBirth": "1970-09-13",
+          "gender": "m",
+          "givenName": "WERNER",
+          "familyName": "MUSTERMANN",
+          "placeOfResidence": {
+            "type": "national",
+            "street": "KURZER WEG 7",
+            "postalCode": "12345",
+            "city": "ANKH-MORPORK"
+          }
+        }
+      },
+      "properties": {
+        "placeOfBirth": {
+          "type": "string",
+          "description": "Geburtsort"
+        },
+        "dateOfBirth": {
+          "type": "string",
+          "format": "date",
+          "description": "Geburtsdatum"
+        },
+        "gender": {
+          "type": "string",
+          "enum": [
+            "m",
+            "w",
+            "x",
+            "d"
+          ],
+          "description": "Geschlecht (m=männlich, w=weiblich, x=keine Angabe, d=divers)"
+        },
+        "nationality": {
+          "type": "string",
+          "description": "Nationalität"
+        },
+        "artisticName": {
+          "type": "string",
+          "description": "Künstler- oder Ordensname"
+        },
+        "doctoralDegrees": {
+          "type": "string",
+          "description": "Akademischer Titel, z.B. \"Dr.\" oder \"Prof.\""
+        },
+        "birthName": {
+          "type": "string",
+          "description": "Geburtsname"
+        },
+        "givenName": {
+          "type": "string",
+          "description": "Vorname(n)"
+        },
+        "familyName": {
+          "type": "string",
+          "description": "Familienname"
+        },
+        "placeOfResidence": {
+          "$ref": "#/definitions/Address-national"
+        }
+      }
+    },
+    "Phone": {
+      "type": "object",
+      "title": "Phone",
+      "description": "Telefonnumer mit Zusatzinformationen",
+      "additionalProperties": false,
+      "properties": {
+        "number": {
+          "type": "string",
+          "title": "Phone Number",
+          "description": "Telefonnummer gemäß ITU E.123. Es soll das internationalen Format, z.B. \"+49 89 32168-42\" verwendet werden.",
+          "example": "+49 89 32168-42",
+          "maxLength": 23
+        },
+        "mobile": {
+          "type": "boolean",
+          "description": "Zeigt an, ob es sich um eine Mobilfunknummer handelt."
+        },
+        "description": {
+          "type": "string",
+          "description": "Beschreibung der Art der Telefonnummer"
+        }
+      },
+      "required": [
+        "number"
+      ],
+      "x-examples": {
+        "example-1": {
+          "number": "+49 89 32618",
+          "mobile": false,
+          "description": "Rosis Nummer"
+        },
+        "example-2": {
+          "number": "(089) 32618",
+          "mobile": false,
+          "description": "Rosis Nummer"
+        }
+      }
+    }
+  }
+}

spec/zustelldienst.yml

 openapi: 3.0.0
 info:
-  version: '1.0.0-alpha'
+  version: 'API_VERSION'
   title: Antragsmanagement API für Antragsverfahren und Berichtspflichten
-  description: Übergreifende API Schnittstelle des Zustelldienstes.
   contact:
     name: FITKO
     url: 'https://www.fitko.de/'

ui/config.js.template

 // Localhost: python -m http.server
-// sed 's,REPLACEME,https://example.com/spec.yml,g' ui/config.js.template > ui/config.js
+// sed 's,API_VERSION,https://example.com/spec.yml,g' ui/config.js.template > ui/config.js
 
-export const SPEC_URL = "REPLACEME";
+export const SPEC_URL = "API_VERSION";

ui/index.html

@@ -16,14 +16,17 @@
 <!--<rapi-doc spec-url = "poc/reference/0_xfall_deref_snippets.json" -->
 <rapi-doc id="thedoc"
           render-style="focused"
-          show-info="true"
-          show-header="true"
-          show-components="true"
+
           theme="light"
           xprimary-color="#11171a"
           header-color="#263238"
           nav-bg-color="#263238"
 
+          show-info="true"
+          show-header="true"
+          show-components="true"
+          allow-spec-file-load="false"
+
           info-description-headings-in-navbar="true">
     <!-- content at the top -->