From b28dbffc0dd50369d73969027533b0febf4de376 Mon Sep 17 00:00:00 2001 From: Thomas Cederholm Date: Mon, 11 May 2026 13:57:43 +0200 Subject: [PATCH] docs: Reprioritize OpenAPI gap inventory Wave 1 and the high-impact slices of Wave 2 (string formats, numeric widths) have landed. Reorder the remaining work so that parameter/request-body fidelity (old Wave 3) and refs/spec topology (old Wave 5) come first, with extensions (old #29) pulled forward into the new Wave 2. Niche JSON Schema keywords (object: orig #6, array: orig #7) are demoted to a later wave. Original item numbers are preserved in parentheses for back-reference. --- .../2026-05-07-openapi-refactor-design.md | 69 ++++++++++--------- 1 file changed, 38 insertions(+), 31 deletions(-) diff --git a/docs/superpowers/specs/2026-05-07-openapi-refactor-design.md b/docs/superpowers/specs/2026-05-07-openapi-refactor-design.md index ec3b744..379d60d 100644 --- a/docs/superpowers/specs/2026-05-07-openapi-refactor-design.md +++ b/docs/superpowers/specs/2026-05-07-openapi-refactor-design.md @@ -454,56 +454,63 @@ The following docs reference Java 21 today and must be updated as part of the re Each item below becomes its own small spec/PR after the refactor lands. Listed in the recommended order. -**Wave 1 — high impact, low cost, unblocked by typed model** +> **Reprioritized 2026-05-08.** Wave 1 and the high-impact slices of the original Wave 2 (string formats, numeric widths) have landed. The remaining items have been re-ordered to prioritize parameter/body fidelity, refs/topology, and extensions — the keywords most real-world specs depend on — over niche JSON Schema validation keywords. Item numbering follows the original inventory in parentheses so historical references still resolve. + +**Wave 1 — high impact, low cost, unblocked by typed model — ✅ DONE** 1. `requestBody.required: true` enforcement when body is empty. 2. `additionalProperties: false` and `additionalProperties: { schema }` enforcement. 3. Combinators: `oneOf` / `anyOf` / `allOf` (one spec — they share machinery). 4. `not` + `const` + top-level `enum` + schema booleans (`true` / `false`). -**Wave 2 — coverage breadth** +**Wave 2 (original, partially done — string formats and numeric widths)** + +5. ✅ Format expansion: `email`, `uri`, `uri-reference`, `hostname`, `ipv4`, `ipv6`, `regex`, `byte` (base64), `binary`, `password`. +8. ✅ Format-driven width validation: `int32` / `int64` overflow, `float` / `double` precision. + +Items 6 and 7 from the original Wave 2 are demoted to the new Wave 4 below. + +**Wave 2 — parameter & request-body fidelity + extensions (new)** -5. Format expansion: `email`, `uri`, `uri-reference`, `hostname`, `ipv4`, `ipv6`, `regex`, `byte` (base64), `binary`, `password`. -6. Object: `patternProperties`, `dependentRequired`, `dependentSchemas`, `propertyNames`. -7. Array: `contains` / `minContains` / `maxContains`, `prefixItems` (tuple validation). -8. Format-driven width validation: `int32` / `int64` overflow, `float` / `double` precision. +- (orig #9) Parameter `style` + `explode` for `query`, `path`, `header`, `cookie`. +- (orig #10) Array query parameters (`?ids=1&ids=2` and `?ids=1,2`). +- (orig #11) `deepObject` query style. +- (orig #12) `content` instead of `schema` on parameters. +- (orig #13) `cookie` parameter location. +- (orig #14) Media-type ranges (`application/*`, charset suffix tolerance). +- (orig #15) Non-JSON request bodies: `application/x-www-form-urlencoded`, `multipart/form-data`, `text/plain`. `encoding` object on multipart fields. +- (orig #29) Extensions (`x-*` keys) — at minimum: silently preserved, accessible via raw map fallback. Pulled forward from old Wave 6 because consumers rely on vendor extensions across the spec. -**Wave 3 — parameter & request-body fidelity** +**Wave 3 — refs & spec topology (new)** -9. Parameter `style` + `explode` for `query`, `path`, `header`, `cookie`. -10. Array query parameters (`?ids=1&ids=2` and `?ids=1,2`). -11. `deepObject` query style. -12. `content` instead of `schema` on parameters. -13. `cookie` parameter location. -14. Media-type ranges (`application/*`, charset suffix tolerance). -15. Non-JSON request bodies: `application/x-www-form-urlencoded`, `multipart/form-data`, `text/plain`. `encoding` object on multipart fields. +- (orig #19) Cross-document `$ref`. +- (orig #20) JSON Schema `$defs` (3.1 alternative to `components.schemas`). +- (orig #21) `$dynamicRef` / `$dynamicAnchor` (rarely used). +- (orig #22) Multiple `servers[]` entries; server variables (`{tenant}.example.com`). +- (orig #23) Path-level parameters (defined on `PathItem`, shared across operations). +- (orig #24) Path-level / operation-level `servers`. -**Wave 4 — responses** +**Wave 4 — niche JSON Schema keywords (demoted)** -16. Validate response body against `responses[status].content[mediaType].schema`. -17. Validate response headers. -18. `default` response handling. +- (orig #6) Object: `patternProperties`, `dependentRequired`, `dependentSchemas`, `propertyNames`. +- (orig #7) Array: `contains` / `minContains` / `maxContains`, `prefixItems` (tuple validation). -**Wave 5 — refs & spec topology** +**Wave 5 — responses** -19. Cross-document `$ref`. -20. JSON Schema `$defs` (3.1 alternative to `components.schemas`). -21. `$dynamicRef` / `$dynamicAnchor` (rarely used). -22. Multiple `servers[]` entries; server variables (`{tenant}.example.com`). -23. Path-level parameters (defined on `PathItem`, shared across operations). -24. Path-level / operation-level `servers`. +- (orig #16) Validate response body against `responses[status].content[mediaType].schema`. +- (orig #17) Validate response headers. +- (orig #18) `default` response handling. **Wave 6 — UX & metadata** -25. Multi-error collection (gather all failures per request, not first-only). -26. `discriminator` (used with combinators). -27. `readOnly` / `writeOnly` (skip validation in the wrong direction). -28. `deprecated` (warning logging on use). -29. Extensions (`x-*` keys) — at minimum: silently preserved, accessible via raw map fallback. +- (orig #25) Multi-error collection (gather all failures per request, not first-only). +- (orig #26) `discriminator` (used with combinators). +- (orig #27) `readOnly` / `writeOnly` (skip validation in the wrong direction). +- (orig #28) `deprecated` (warning logging on use). **Wave 7 — last** -30. Security: `securitySchemes` parsing; `security` enforcement at operation level. +- (orig #30) Security: `securitySchemes` parsing; `security` enforcement at operation level. ## Out of scope for this design