retrofit: reverse-spec oas-generation (5 new REQs / 19 methods annotated)

[rubenvdlinde]

Summary

Reverse-spec retrofit for the oas-generation capability — lifts five observed sub-behaviors into the spec and annotates the 19 substantive methods with @spec tags. Generated from the Bucket 2a scan (/tmp/or-scan/rspec-cluster-oas-generation.json, 33 methods / 9 files); 14 of the 33 are DTO accessors, trivial constructors, exception getters, or a stub resolver and were dropped as false positives.

New REQs (5)

1. ETag computation + If-None-Match short-circuit — deterministic SHA-256 over canonicalised JSON; RFC 7232 weak comparison; 304 Not Modified skip-on-?validate=true.
2. RFC 7807 problem-details shape — application/problem+json for the OAS endpoint's 404/409/422 responses; custom extensions cannot overwrite standard fields.
3. OasValidationReport contract — issue collection with error/warning/auto_corrected severity and 10 stable CODE_* machine codes; toSummary() shape drives x-validation-summary extension and strict-mode 422 body.
4. Opt-in request-body validation middleware — ?_validate=true gates JSON-Schema validation on POST/PUT/PATCH; failure → 422 problem-json via OasValidationFailureException → afterException. Resolver is currently a stub; the REQ documents the contract the future implementation must satisfy.
5. Internal validation pipeline — sanitizePropertyDefinition (23-keyword OpenAPI 3.1 whitelist + auto-coercion), NLGov API-01 (allowed HTTP methods → error), NLGov API-03 (allowed status codes → warning), OpenAPI 3.1 meta-schema validation (best-effort; validator errors logged but swallowed).

Annotated methods (19)

• lib/Service/Oas/OasETagComputer.php — hash, matches, canonicalise (task-1)
• lib/Service/Oas/ProblemDetailsBuilder.php — validationFailed, notFound, conflict (task-2)
• lib/Service/Oas/OasValidationReport.php — addError, addWarning, addAutoCorrection (task-3)
• lib/Service/Oas/OasRequestValidator.php — validate, isValid, collectErrors (task-4)
• lib/Middleware/OasValidationMiddleware.php — beforeController, afterException (task-4)
• lib/Service/OasService.php — sanitizePropertyDefinition, validateAgainstMetaSchema, validateNlGovRules (task-5)
• lib/Controller/OasController.php — boolQueryParam (task-5)

Dropped as false positives (14)

• OasValidationReport read-accessors (getIssues, getErrors, getWarnings, getAutoCorrections, hasErrors, passed, isEmpty, toSummary, filterBySeverity) — pure consequence of the setters; annotating them would clutter the spec.
• OasValidationException / OasValidationFailureException __construct + getters — exception wiring.
• OasService::__construct, OasService::getLastValidationReport — DI plumbing + trivial accessor.
• OasValidationMiddleware::resolveOperationSchema — explicit stub returning null; REQ documents the contract for the future implementation, not the stub.

Drift flagged

OasValidationMiddleware::resolveOperationSchema is a stub returning null, so the validation middleware is effectively a no-op today — even when ?_validate=true is set. REQ-006 documents the eventual contract so the future implementation has a target. This is a known gap, not a regression. Consumers needing validation can still call OasRequestValidator::validate() directly.

Test plan

• OpenSpec validate: openspec validate retrofit-2026-05-24-oas-generation --strict
• PHPCS check on the 7 modified files (annotations follow the format used elsewhere on this branch — see OasController existing @spec tags).
• No behavior change — documentation/coverage only.

[github-actions]

Quality Report — ConductionNL/openregister @ 77b14d6

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	❌
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		❌
stylelint		❌
composer			✅	✅ 162/162
npm			✅	✅ 532/532
PHPUnit					⏭️
Newman					⏭️
Playwright					⏭️

---

Quality workflow — 2026-05-24 18:30 UTC

Download the full PDF report from the workflow artifacts.