# oPJD-Konformität

Was „oPJD-konform" bedeutet, in drei aufeinander aufbauenden Stufen — und welche
Versionen für den Austausch gültig sind.

## Konformitätsstufen

### Stufe 1 — schema-valide

> Das Paket validiert ohne Fehler gegen das JSON Schema der deklarierten
> `schema_version` (Draft 2020-12, strikte Validierung inkl. Formatprüfung).

### Stufe 2 — referenziell integer

> Zusätzlich: alle IDs paketweit eindeutig; jede Referenz (`tumor_ref`, `events[]`,
> `start_event`/`end_event`, `relation.from`/`to`, `journey_status.*`) löst auf ein
> existierendes Objekt auf; Relationsziele entsprechen dem erwarteten Zieltyp
> (z. B. `triggers` → Episode, `result_of` → Ereignis).

### Stufe 3 — grammatik-geprüft

> Zusätzlich: die Episodengrammatik ist maschinell ausgewertet — Verlaufsphasen je Tumor
> überlappungsfrei, Kontextklammern parallel zulässig, Erwartungsregeln je Episodentyp
> (z. B. neoadjuvant erwartet eine assesses-Beurteilung, Überwachungsepisoden erwarten
> Kontrollereignisse); die Befunde liegen dem Paket bei oder sind abrufbar.

**Deklarationsregel:** Ein Absender darf „oPJD-konform (Stufe n)" nur deklarieren, wenn
die Prüfungen der Stufe automatisiert bestanden sind.

**Prüfwerkzeuge:** Stufe 1 heute via `npm run validate` (Referenzbeispiele) bzw. ajv;
Stufe 1–2 plus Grammatik-Hinweise via MCP-Werkzeug `opjd_validate`; Stufe 3 vollumfänglich
auf Validator-Ebene (ValiQon-Anschluss, in Arbeit).

## Versionsgültigkeit für Austauschpartner

> Neue Pakete deklarieren in `schema_version` eine Version mit Status `released`
> (bevorzugt `latest_released`); während der 0.x-Phase ersatzweise die aktuelle
> draft-/review-Version nach bilateraler Absprache. Empfänger müssen alle Versionen mit
> Status `released` sowie `deprecated` (bis `sunset_at`) annehmen.

Lebenszyklus-Definitionen: siehe [`versions.json`](../../public/schema/versions.json)
(`lifecycle`) — draft (Entwurf), review (Konsultation), released (Freigegeben),
deprecated (Abgekündigt), retired (Zurückgezogen). Zulässige Übergänge:
`draft→review`, `review→draft` (Rückläufer), `review→released`, `released→deprecated`,
`deprecated→retired`, `draft→retired` (verworfen). `released` ist eine Einbahnstraße.

**Einfrier-Regel:** Ab Status `released` ist die Schemadatei byte-eingefroren;
`versions.json` führt ihre SHA-256-Prüfsumme, die CI erzwingt sie. Korrekturen — auch
Tippfehler — erzeugen eine neue Patch-Version.

## Kompatibilitätszusagen

> Innerhalb einer Major-Linie ab 1.0 gilt: Ein Empfänger, der 1.x liest, liest jede 1.y
> (y ≥ x); neue optionale Felder darf er ignorieren. Enum-Werte werden nie entfernt oder
> umbenannt, sondern als deprecated markiert und frühestens in der nächsten Major-Version
> entfernt. Pflichtfelder werden innerhalb einer Major-Linie nie hinzugefügt.

Term-Identitäten (`opjd://…`) sind versionsübergreifend stabil; Lebenszyklus je Term über
`deprecated_in`/`superseded_by` im Dictionary.