register-referentie/docs/architecture/adr-0021-acl-resolves-zaaktype-by-identificatie.md

ADR-0021: The ACL resolves its zaaktype by identificatie, not a pinned URL

• Status: Accepted
• Date: 2026-07-22
• Deciders: Respellion engineering
• Relates to: S-27 (#113), proposed in #117. The cleaner design deliberately split out of S-B04 (#110, ADR-0020), which fixed the local stack with an infra-only bootstrap.

Context

The ACL was handed a pinned zaaktype URL (Acl__Defaults__ZaaktypeUrl) and diploma informatieobjecttype URL. OpenZaak assigns those UUIDs at creation, so the URL is not knowable when the compose file is written — every stack had to seed the catalogus and then capture + inject the resulting URLs out of band: run-domain-check.sh for CI, and the local-seed → acl.env bootstrap (ADR-0020) for make local. Brittle, and a stale/placeholder URL failed opaquely (OpenZaak 400).

Decision

The ACL resolves its zaaktype (by identificatie) and diploma informatieobjecttype (by omschrijving) from OpenZaak's Catalogi API, instead of being handed the URLs.

• Config: AclDefaults.ZaaktypeUrl/InformatieobjecttypeUrl → ZaaktypeIdentificatie (BIG-REGISTRATIE) / InformatieobjecttypeOmschrijving (Diploma).
• Lookup (gateway, §8.1): GET /catalogi/api/v1/zaaktypen?status=definitief&identificatie=… → the published zaaktype URL; GET /catalogi/api/v1/informatieobjecttypen?status=definitief matched on omschrijving. Reuses the gateway's existing catalogus-query machinery.
• Timing = lazy + cached (CachedZaaktypeCatalog). Resolve on first use (first zaak open / document store) and cache for the process lifetime. Lazy avoids a startup ordering coupling — the ACL never crash-loops when it boots before the catalogus is published. A failed resolution is not cached, so it is retried on the next call (e.g. once the zaaktype is published); a restart re-resolves.
• Failure mode: no published match → a clear "No published zaaktype with identificatie '…' found in OpenZaak — is the BIG catalogus seeded and published?" error, replacing the opaque placeholder 400.

Consequences

Positive

• No stack captures or injects a server-assigned URL any more: run-domain-check.sh drops the ACL_ZAAKTYPE_URL/ACL_INFORMATIEOBJECTTYPE_URL capture+inject, docker-compose.yml/.local.yml drop the placeholder URL env, and local-seed/acl.env shrink to a single line. The ACL self-configures from the catalogus it already talks to.
• The failure mode is legible (a named error instead of a 400 on a zeros-UUID).

Negative / costs

• The ACL still needs its OpenZaak BaseUrl pointed at a URL-valid host (a container IP), so the base-URL injection from ADR-0020 stays (the local acl.env now carries only that; CI keeps ACL_OPENZAAK_BASEURL). This is not something S-27 can remove: OpenZaak validates the zaaktype field on zaak-create with Django's URLValidator and rejects a single-label host (http://openzaak:8000/… → zaaktype: bad-url, "Voer een geldige URL in.", confirmed empirically). So ADR-0020's seed-env volume + ACL entrypoint shim are simplified, not deleted.
• New branching in the gateway/resolver → unit + integration test surface; the mutation ratchet covers it (§5).
• A seed step still creates + publishes the zaaktype (this ADR changes only discovery). Reaching OpenZaak's Catalogi API to seed likewise needs the IP host (its query params hit the same URLValidator) — unchanged from before.

Alternatives considered

• Resolve at startup (eager). Simpler cache, but reintroduces the ordering coupling (crash-loop if the catalogus isn't published yet). Rejected in favour of lazy.
• Per-request resolution (no cache). No stale-cache risk, but a Catalogi lookup on every ACL operation. Rejected; a process-lifetime cache with restart-to-refresh is enough here.
• Keep the pinned URL (status quo / ADR-0020 only). Rejected — the brittleness this ADR removes is exactly what S-27 was carved out to fix.