register-referentie/docs/architecture/adr-0002-catalogus-design.md

ADR-0002: BIG catalogus design and OpenZaak seeding

• Status: Accepted
• Date: 2026-06-03
• Deciders: Respellion engineering
• Relates to: S-01 (#2)

Context

S-01 needs a reproducible BIG catalogus in OpenZaak with a lean BIG-registratie zaaktype (only schema-mandatory fields) plus a bsn eigenschap, and a JWT client that can list zaaktypen. We had to decide how to provision this idempotently at startup.

Findings from the OpenZaak image (openzaak/open-zaak:latest):

• setup_configuration (run by the init container) is declarative and idempotent, with steps for JWT secrets and applicaties (vng_api_common_credentials, vng_api_common_applicaties) — but no step for catalogi/zaaktypen.
• Catalogus/zaaktype/eigenschap can only be created through the ZTC REST API.
• Publishing a zaaktype requires ≥1 roltype, ≥1 resultaattype and ≥2 statustypen.

Decision

1. Provision the JWT client declaratively via infra/openzaak/setup_configuration/data.yaml: a JWTSecret (big-reference-seed / dev secret) and an Applicatie with heeft_alle_autorisaties: true. Idempotent, runs in the init container.
2. Seed the catalogus/zaaktype/eigenschap via the ZTC API with an idempotent, stdlib-only script (infra/openzaak/seed_catalogus.py, make openzaak-seed). It mints a ZGW JWT from the provisioned client and matches existing objects (by domein / identificatie / naam, querying status=alles so concepts are seen) before creating.
3. Keep the zaaktype a CONCEPT (not published). Publishing pulls in roltypen, statustypen and resultaattypen, which go beyond "schema-mandatory"; those arrive with the workflow/zaak slices that actually need a published type. Listing uses status=alles.
4. Disable outbound notifications (NOTIFICATIONS_DISABLED=true) until Open Notificaties (NRC) lands in S-01-c — otherwise every ZTC write 500s trying to notify.
5. Fixed dev values: RSIN 517439943 (elfproef-valid test value); the JWT secret is dev-only and documented as such.

Consequences

• Reproducible & version-robust: the API-driven seed doesn't depend on fixture PKs or a catalogi setup_configuration step that may change between versions.
• Teaches the pattern: the seed talks to OpenZaak exactly the way the ACL will later — through the documented ZGW API, with a JWT (ADR-0001).
• The seed is a script, but a data loader is explicitly anticipated (PRD §8); it lives under infra/openzaak/, not as ad-hoc tooling.
• Follow-ups: re-enable notifications when NRC is up (S-01-c); publish the zaaktype (add the related types) when a slice needs to create real zaken; pin the OpenZaak image tag.

Alternatives considered

• Fully declarative in data.yaml — rejected: no catalogi/zaaktype step exists.
• Django loaddata fixture — rejected: brittle, tied to model PKs and the exact image version; bypasses the API the rest of the system uses.