45 lines
4.7 KiB
Markdown
45 lines
4.7 KiB
Markdown
# 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`](../docs/architecture/v1.1.md#user-content-61-fachliche-integritätsprüfung--schema-versionierung-verbindlich)).
|
|
|
|
**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-Form
|
|
- `ds/<domain>/<resource>` — Datenquellen-Rückgabe
|
|
- `sink/<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).
|