4.7 KiB
ProofedMesh Schemas
Versionierte JSON-Schemas für die kanonischen Business-, Datenquellen- und Senken-Formate. Jedes Schema trägt am Objekt-Root schema.name und schema.version, damit Attestierungen die genutzte Fassung mit-signieren können (siehe docs/architecture/v1.1.md).
Versionspolitik: Breaking Changes bekommen eine neue Hauptversion (v1.0.0 → v2.0.0). Nicht-breaking Erweiterungen eine Minor- oder Patch-Version. Alte Versionen werden niemals verändert — sie werden parallel vorgehalten, solange Attestierungen aus ihrer Laufzeit noch verifizierbar sein müssen (Default-Retention 1 Jahr, siehe PII-Retention-ADR).
Vorhandene Schemas
| Pfad | Rolle | Status | Verwendet in |
|---|---|---|---|
expense/canonical/v1.0.0.json |
Kanonische Business-Form | legacy | Approval-Attestierung (subject, materials), Agent-A-Transform-Output |
expense/canonical/v1.1.0.json |
Kanonische Business-Form | legacy | wie v1.0.0, zusätzlich mit Zeilen-Allokationen (Multi-Projekt pro Item) |
expense/canonical/v1.2.0.json |
Kanonische Business-Form | aktiv | wie v1.1.0, zusätzlich mit receipt_content_hash/receipt_attestation_ref je Item und neuen Item-Typen PER_DIEM_* |
ds/expense/project_assignment/v1.0.0.json |
Datenquellen-Rückgabe | aktiv | Query Attestation von ds:expense-db-app / project_assignments |
ds/receipts/v1.0.0.json |
Datenquellen-Rückgabe | aktiv | Query Attestation von ds:receipts / receipt (Metadaten; Blob kommt separat) |
ds/per_diem/v1.0.0.json |
Datenquellen-Rückgabe | aktiv | Query Attestation von ds:per-diem-rates / rates |
sink/db/expense/v1.0.0.json |
Senken-Payload | legacy | Transform-Attestierung expense.map_to_sink → sink:expense-db-app (ohne Splits) |
sink/db/expense/v1.1.0.json |
Senken-Payload | legacy | wie v1.0.0, zusätzlich mit per-Item-Allocation-Rows für die DB-App |
sink/db/expense/v1.2.0.json |
Senken-Payload | aktiv | wie v1.1.0, zusätzlich mit Receipts- und PER_DIEM_*-Item-Support |
Neue Workflows SOLLEN die v1.2.0-Fassungen nutzen. Ältere Versionen bleiben parallel bestehen, damit Attestierungen aus deren Laufzeit verifizierbar bleiben.
Zeilen-Allokationen (v1.1.0)
Jedes expense_items[] darf ein optionales allocations[]-Array tragen. Jede Allocation referenziert ein project_code+cost_center+source_attestation_ref und trägt entweder einen Prozentsatz (mode: "percentage", Feld percentage) oder einen absoluten Betrag (mode: "absolute", Feld amount). Alle Entries desselben Items müssen denselben Modus haben. OPA erzwingt Summenerhalt: sum(percentage) == 100.00 bzw. sum(amount) == item.amount.
Die Senkenfassung (sink.db.expense v1.1.0) erwartet immer absolute Beträge — Agent B löst percentage→absolute vor der Senkenübergabe auf und trägt die ursprüngliche percentage als informatives Feld mit.
Beispiele unter */examples/vX.Y.Z/*.json (werden in CI gegen das Schema derselben Version validiert).
Receipts (v1.2.0)
Jedes expense_items[] darf ein receipt_content_hash + receipt_attestation_ref tragen. Der eigentliche Beleg liegt im PII-Store, nur Hash und Attestations-Referenz landen in der kanonischen Fassung. Lesender Zugriff auf den Blob erfolgt über ds:receipts + Session-Scope-Token nach OPA-Prüfung (siehe policies/data_sources/receipts.rego und docs/architecture/v1.1.md §4.7).
Per-Diem-Items (v1.2.0)
Neue Item-Typen PER_DIEM_FULL, PER_DIEM_PARTIAL, PER_DIEM_ARRIVAL, PER_DIEM_DEPARTURE kennzeichnen vom agent-per-diem-calculator deterministisch erzeugte Zeilen. Diese Items MÜSSEN ein computed_from.transform_attestation_ref tragen (JSON-Schema erzwingt es per if/then), damit die Rückverfolgung zur Berechnungs-Attestation und Rate-Query-Attestation gewährleistet ist (siehe docs/architecture/v1.1.md §6.2).
Namensschema
expense/canonical— kanonische (senken-unabhängige) Business-Formds/<domain>/<resource>— Datenquellen-Rückgabesink/<kind>/<domain>— Senken-Payload
Pfad: <namespace>/.../v<major>.<minor>.<patch>.json. $id enthält die absolute URL unter https://basicstack.de/schemas/... (identisch zum Dateipfad).