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       | **aktiv** | wie v1.0.0, zusätzlich mit Zeilen-Allokationen (Multi-Projekt pro Item) |
| `ds/expense/project_assignment/v1.0.0.json`     | Datenquellen-Rückgabe          | aktiv     | Query Attestation von `ds:expense-db-app` / `project_assignments` |
| `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                 | **aktiv** | wie v1.0.0, zusätzlich mit per-Item-Allocation-Rows für die DB-App |

Neue Workflows SOLLEN die v1.1.0-Fassungen nutzen. v1.0.0 bleibt 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).

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