# ED-01-002 – Transport Mapping ## Status Draft v0.1 ## Übergeordnetes Arbeitspaket [ED-01 – Context Mapping](ED-01_Context_Mapping.md) ## Vorgänger [ED-01-001 – Domain Model](ED-01-001_Domain_Model.md) ## Ziel Dieser Arbeitsschritt erweitert das bestehende OpenRefine-Request-Mapping um die Überführung der im `properties`-Array gelieferten Context Properties in transportneutrale Eingabedaten für das Reconcilix Domain Model. Die fachlichen Kontextinformationen werden anhand von - `pid` als `contextTypeUri` - `v` als `value` abgebildet. Die eigentliche Zuordnung der erzeugten Context-Daten zu einem `SourceValue` und ihre Übergabe an die Application-Schicht erfolgt in `ED-01-003`. ## Ausgangssituation OpenRefine überträgt zusätzliche Kontextinformationen im Reconciliation-Request über das optionale `properties`-Array. Beispiel: ```json { "query": "Bronze", "type": "http://matcult-the.vocnet.org/00000019", "properties": [ { "pid": "https://reconcilix.vocnet.org/context/0001", "v": "1Skulptur" } ] } ``` `PRE-ED-01A` hat den Transport dieser Properties von OpenRefine zum Reconcilix-Endpunkt nachgewiesen. `ED-01-001` führt das Domain-Objekt `ContextItem` mit den Eigenschaften ```text contextTypeUri value ``` ein. ## Mapping-Regel Jeder Eintrag des OpenRefine-`properties`-Arrays wird einzeln abgebildet: ```text properties[n].pid ↓ contextTypeUri properties[n].v ↓ value ``` Beispiel: ```json { "pid": "https://reconcilix.vocnet.org/context/0001", "v": "..." } ``` wird zu: ```text ContextInput ------------ contextTypeUri = https://reconcilix.vocnet.org/context/0001 value = ... ``` `ContextInput` bezeichnet dabei die transportnahe Repräsentation. Die konkrete Benennung der Klasse richtet sich nach den bereits im Projekt verwendeten Request- und Command-Strukturen. ## Verantwortlichkeit Das Transport Mapping ist verantwortlich für: - das Erkennen eines vorhandenen `properties`-Arrays, - die Iteration über alle übertragenen Properties, - die Abbildung von `pid` auf `contextTypeUri`, - die Abbildung von `v` auf `value`, - die Erhaltung der Reihenfolge der übertragenen Properties, - die Übergabe der gemappten Kontextdaten an die nachfolgende Schicht. Das Transport Mapping ist nicht verantwortlich für: - die fachliche Interpretation des Wertes, - die Prüfung der URI gegen `VOC001_Context_Types`, - die Prüfung der Zulässigkeit für einen Entity Type, - die Persistierung, - die Verwendung in der Candidate Discovery. ## Verhalten ohne Context Properties Fehlt das Feld `properties`, wird eine leere Context-Liste erzeugt. Beispiel: ```json { "query": "Bronze" } ``` Ergebnis: ```text contextItems = [] ``` Das bisherige Verhalten des Reconciliation-Requests bleibt unverändert. ## Verhalten bei mehreren Context Properties Alle übertragenen Context Properties werden übernommen. Beispiel: ```json { "query": "Kiel", "properties": [ { "pid": "https://reconcilix.vocnet.org/context/0003", "v": "Schleswig-Holstein" }, { "pid": "https://reconcilix.vocnet.org/context/0004", "v": "54.3233,10.1228" }, { "pid": "https://reconcilix.vocnet.org/context/0009", "v": "Landeshauptstadt an der Kieler Förde" } ] } ``` Ergebnis: ```text contextItems[0] contextTypeUri = .../0003 value = Schleswig-Holstein contextItems[1] contextTypeUri = .../0004 value = 54.3233,10.1228 contextItems[2] contextTypeUri = .../0009 value = Landeshauptstadt an der Kieler Förde ``` ## Eingabevalidierung Für die Erstimplementierung gelten minimale strukturelle Anforderungen. Ein Property-Eintrag wird nur übernommen, wenn - `pid` vorhanden ist, - `pid` nicht leer ist, - `v` vorhanden ist. Der Wert von `v` darf ein leerer String sein, sofern das bestehende Transportmodell leere Werte grundsätzlich zulässt. Eine fachliche Validierung des Context Types oder des Inhalts erfolgt nicht. Das konkrete Fehlerverhalten bei strukturell ungültigen Einträgen soll sich am bestehenden Verhalten des `OpenRefineRequestMapper` orientieren: - entweder Ablehnung des gesamten Requests, - oder Ignorieren des ungültigen Property-Eintrags. Vor der Implementierung ist das bestehende Mapper-Verhalten zu prüfen und konsistent fortzuführen. ## Datentyp des Wertes OpenRefine überträgt `v` in den derzeit getesteten Requests als String. Für ED-01 wird `value` daher ohne fachliche Typisierung als String behandelt. Beispiele: - XML-Fragmente, - Freitext, - Datumsangaben, - Koordinaten, - interne DatenXML-Fragmente. Eine spätere typabhängige Verarbeitung bleibt möglich, ist aber nicht Bestandteil dieses Arbeitsschritts. ## Betroffene Komponenten Voraussichtlich betroffen: - `OpenRefineRequestMapper` - transportnahe Request- oder DTO-Klassen - zugehörige Mapper-Tests Nicht betroffen: - Candidate Discovery Adapter - Repositories - Persistence Mapper - Datenbankschema ## Tests Mindestens folgende Fälle sind abzudecken: ### Request ohne `properties` Erwartung: ```text contextItems = [] ``` ### Request mit einem Property Erwartung: - genau ein gemappter Context-Eintrag, - `pid` vollständig als `contextTypeUri` übernommen, - `v` unverändert als `value` übernommen. ### Request mit mehreren Properties Erwartung: - alle Einträge werden übernommen, - Reihenfolge bleibt erhalten, - keine Werte gehen verloren. ### Property mit XML-Inhalt Erwartung: - XML wird als unveränderter String übernommen, - keine XML-Interpretation oder Normalisierung. ### Property mit Text Context Erwartung: - Freitext wird unverändert übernommen. ### Strukturell ungültiges Property Erwartung: - Verhalten entspricht der bestehenden Validierungsstrategie des Request-Mappers, - Verhalten ist durch einen Test dokumentiert. ## Nicht Bestandteil Nicht Bestandteil von `ED-01-002` sind: - Erzeugung vollständiger `SourceValue`-Aggregate, - Zuordnung der ContextItems zum Domain-Objekt `SourceValue`, - Erweiterung von Commands oder Application Services, - Persistierung, - Candidate Discovery, - Validierung gegen `VOC001_Context_Types`, - Entity-Type-spezifische Zulässigkeitsprüfungen, - Abhängigkeiten von Vocabulary, Tenant oder Provider. ## Abnahmekriterien - Das OpenRefine-`properties`-Array wird vollständig gemappt. - `pid` wird als `contextTypeUri` übernommen. - `v` wird unverändert als `value` übernommen. - Requests ohne `properties` verhalten sich unverändert. - Mehrere Properties werden vollständig und in stabiler Reihenfolge verarbeitet. - Die bestehende Validierungsstrategie des Request-Mappers bleibt konsistent. - Unit-Tests für alle definierten Mapping-Fälle sind vorhanden. - Alle bestehenden Tests bleiben erfolgreich. ## Nachfolger [ED-01-003 – Application Integration](ED-01-003_Application_Integration.md)