deps: migrate to OpenAPI 3.1+ and use unevaluatedProperties for strict validation

[ericfitz]

Summary

Migrate the OpenAPI specification from 3.0.3 to 3.1+ to enable proper use of unevaluatedProperties: false for strict request validation in schemas that use allOf composition.

Background

TMI uses allOf composition in the OpenAPI spec to:

• Separate request-only and response-only fields (e.g., DfdDiagramInput vs DfdDiagram)
• Compose schemas from base types (e.g., Node extends Cell)

The Problem

In OpenAPI 3.0 / JSON Schema draft-07, additionalProperties: false at the top level of a schema with allOf causes validation to reject properties that ARE defined in the referenced schemas. This is because additionalProperties applies to the local schema level, not the merged result.

Example: The Node schema had:

{
  "allOf": [
    { "$ref": "#/components/schemas/Cell" },
    {
      "properties": {
        "angle": { "type": "number" },
        ...
      }
    }
  ],
  "additionalProperties": false  // This rejects "angle" even though it's defined above!
}

Current Workaround

We removed additionalProperties: false from schemas that use allOf:

• Node
• Edge
• DfdDiagram
• DfdDiagramInput
• Note
• Asset
• ExtendedAsset

This allows X6 diagram properties (like angle, zIndex, etc.) to pass validation, but loses strict validation on these schemas.

Solution

OpenAPI 3.1 (based on JSON Schema 2020-12) introduces unevaluatedProperties: false, which is designed to work correctly with schema composition. It considers properties from all composed schemas as "evaluated" and only rejects truly unknown properties.

Blocked By

• oapi-codegen: Currently only supports OpenAPI 3.0.x. Track progress at: OpenAPI 3.1 support? oapi-codegen/oapi-codegen#373

Tasks

• Monitor oapi-codegen for OpenAPI 3.1 support
• When supported, update openapi field in spec from 3.0.3 to 3.1.0
• Replace additionalProperties: false with unevaluatedProperties: false in affected schemas
• Update any nullable fields to use type: ["string", "null"] syntax (3.1 change)
• Validate with updated tooling
• Regenerate API code
• Run full test suite

References

• JSON Schema unevaluatedProperties
• OpenAPI 3.1 Migration Guide
• oapi-codegen OpenAPI 3.1 issue

Labels

• enhancement
• schema
• blocked

[ericfitz]

Status Check (2026-03-09)

Verdict: Still blocked. No path forward yet.

Findings

• oapi-codegen issue #373 remains open — OpenAPI 3.1 is not supported.
• The migration PR to libopenapi/pb33f (#1388) was closed without merging.
• The underlying parser (kin-openapi) also lacks 3.1 support (issue feat: add security_reviewer query parameter to GET /threat_models #230 still open).
• The maintainer has indicated meaningful progress likely requires sponsorship.
• Latest oapi-codegen release (v2.6.0, 2026-02-27) contains no 3.1-related features.
• TMI's oapi-codegen ecosystem dependencies (runtime v1.2.0, gin-middleware v1.0.2, kin-openapi v0.133.0) are already current — nothing to upgrade to.

Impact on TMI

• TMI continues to use OpenAPI 3.0.3, which means unevaluatedProperties: false cannot be used with allOf composition.
• The current workaround (removing additionalProperties: false from composed schemas) remains necessary.
• Continue monitoring oapi-codegen releases for 3.1 support.

Next check

Re-evaluate in ~3 months or when oapi-codegen releases a version mentioning 3.1 support.

[ericfitz]

Status Check (2026-03-15)

Verdict: Still blocked. No change since last check.

Findings

• oapi-codegen issue #373 remains open — OpenAPI 3.1 is not supported.
• kin-openapi issue feat: add security_reviewer query parameter to GET /threat_models #230 remains open — JSON Schema 2020-12 not implemented.
• Both upstreams indicate the work requires funding to proceed; a prior funding attempt fell through.
• Latest oapi-codegen release (v2.6.0, 2026-02-27) contains no 3.1-related features.
• Latest kin-openapi release (v0.134.0, 2026-03-13) contains bug fixes only, no 3.1 work.
• TMI's oapi-codegen ecosystem dependencies (runtime v1.2.0, gin-middleware v1.0.2, kin-openapi v0.134.0) are already current.

Impact on TMI

• TMI continues to use OpenAPI 3.0.3.
• The workaround (removing additionalProperties: false from composed schemas) remains necessary.
• No alternative path forward without switching code generators entirely (significant migration effort).

Next check

Re-evaluate in ~3 months (June 2026) or when oapi-codegen releases a version mentioning 3.1 support.

[ericfitz]

Dependency Added

Issue #180 has been created to evaluate migration from oapi-codegen to ogen for OpenAPI code generation. This issue (#87) is blocked by #180 — we cannot upgrade the spec to 3.1+ until the code generator supports it.

Given that oapi-codegen has no path to 3.1 support and both upstreams require funding, migrating to a different generator is likely the only viable path forward.