ProofedMesh/schemas/README.md

# 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).