Skip to content

Dokumentation des Metadatenschemas ausbauen

Warum?

Die Dokumentation der Nutzungszenarien und technischer Sachverhalte (Validierung, Datensatzgenerierung/Datenmodell, Versionierung) des Metadatenschemas ist unvollständig und wirft bei einigen Nutzern noch Fragen auf.

Als Entwickler:in bzw. Verfahrensbetreiber eines sendenden Systems, möchte ich in der Dokumentation erläutert bekommen wofür ich das Metadatenschema einsetzen kann, woher ich die Informationen für Metadaten herbekomme bzw. in welchen Szenarien diese für mich relevant sind.

Als Entwickler:in bzw. Verfahrensbetreiber eines empfangenden Systems, möchte ich in der Dokumentation erläutert bekommen wofür ich das Metadatenschema einsetzen kann und wie ich mit den jeweiligen Übermittelten Informationen umgehen muss.

Relevante Links und Bemerkungen

Wenn von Bereichen des Metadatenschemas gesprochen wird, sind folgende Bereiche gemeint:

Akzeptanzkriterien

Es sollen folgende Sachverhalte (besser) beschrieben werden:

  1. Es wird grundsätzlich erklärt, welchen Zweck das Metadatenschema erfüllt.
  2. Folgende Fragestellungen werden für sendende Systeme beantwortet:
    • In welchen Anwendungsfällen sind welche Bereiche relevant.
    • In den jeweiligen Bereich wird erklärt:
      • Woher bekomme ich die Informationen her und wie sind Sachverhalte korrekt zu befüllen?
      • Falls ein externer Standard (identifikationReport, eidas Profile) referenziert wird, werden Basisinformationen über diesen Standard vermittelt bzw. weiterführende Informationen verlinkt.
  3. Folgende Fragestellungen werden für empfangende Systeme beantwortet:
    • Welche Anwendungsfälle werden adressiert
    • Wir sind Informationen zu prüfen / validieren und welche fachliche Bedeutung haben bestimmte Werte
  4. Alle Unterseiten von https://docs.fitko.de/fit-connect/docs/metadata/overview erhalten einen einführenden Text, der die wesentlichen Punkte des jeweiligen Metadaten-Abschnitts erklärt.
  5. Konkrete Beschreibung wie eine JSON Schema-Validierung funktioniert (inkl. Codebeispielen und Zusammenhang zur Schema-Versionierung) -> https://docs.fitko.de/fit-connect/docs/getting-started/receiving/validate
  6. Nutzung des Attributs $schema im Datensatz, um konkret genutztes Schema anzugeben: bsp. "$schema": "https://schema.fitko.de/fit-connect/metadata/0.9.2/metadata.schema.json". Dies soll anhand von Codebeispielen gezeigt werden.
  7. Erläuterung des Versionierungskonzepts und Klarstellung, dass Metadaten unabhängig von der Submission API versioniert werden
  • Möglichkeit bilateraler Extensions werden erläutert
  1. Erläutern, wie JSON Schema für die Generierung von internen Datenmodelle genutzt werden. Verweis auf JSON Schema Tool und Bibliotheken (bspw. https://quicktype.io/)
  2. Die Inhalte aus https://docs.fitko.de/fit-connect/docs/getting-started/submission/metadata werden in den Abschnitt zum Metadatenschema verschoben.
Edited by Marco Holz