feat(gateway): typed DTO contract for HTTP responses and OpenAPI schema

[bburda]

Pull Request

Summary

The gateway's HTTP payloads were maintained as three independent, hand-written representations - the handler's JSON construction, the OpenAPI schema factories, and the XMedkit extension builder - with nothing keeping them in sync. They drifted: entity list responses advertised a minimal schema while the gateway actually emitted rich x-medkit metadata, so generated clients could not see those fields.

This introduces a typed DTO contract. Each payload is a plain C++17 struct described once by a constexpr field list. Three visitors fold over that single description:

• JsonWriter - struct to wire JSON
• SchemaWriter - type to OpenAPI schema
• JsonReader - request body to struct, with validation

Wire output and OpenAPI schema are therefore generated from one source and cannot drift. All HTTP handler domains (entities, faults, operations, configurations, data, locks, triggers, cyclic-subscriptions, bulk-data, logs, scripts, updates, auth, health) were migrated to the contract, and components/schemas is now generated from the DTO registry. The legacy XMedkit fluent builder and the ~50 hand-written schema factories were removed.

Client-observable changes

• The OpenAPI components/schemas is regenerated from the DTOs; several schema names changed (for example the entity list/detail schemas). Clients generated from the previous spec need to be regenerated.
• Entity responses now always include the type discriminator (previously absent on list items).
• Optional fields previously emitted as empty strings or empty arrays are now omitted when empty.
• Request-body validation failures on some PUT/POST endpoints now return the error code invalid-request (HTTP status 400 is unchanged).

Known limitation

The fault/config/data/log list endpoints emit a richer collection-level x-medkit than the generic Collection<T> wrapper schema types it as. The wire payload stays a valid instance of the published schema; this is a schema-precision gap, documented in design/dto_contract.rst.

---

Issue

Part of #338.

This PR makes the gateway spec accurate. #338 stays open until generated clients are regenerated against the corrected spec and downstream consumers updated, which is follow-up work in separate repositories.

---

Type

• Bug fix
• New feature or tests
• Breaking change
• Documentation only

---

Testing

• New test_dto_contract unit suite round-trips every registered DTO through all three visitors and validates each generated schema.
• Integration tests extended: live endpoint responses are validated against the served OpenAPI spec, and the typed x-medkit sub-schemas are asserted present in the spec.
• Full ros2_medkit_gateway and ros2_medkit_integration_tests suites pass (unit, integration, linters); clang-tidy is clean.

Reviewers can verify by building ros2_medkit_gateway, running colcon test, and hitting GET /api/v1/docs to confirm components/schemas contains the typed entity and x-medkit schemas.

---

Checklist

• Breaking changes are clearly described (and announced in docs / changelog if needed)
• Tests were added or updated if needed
• Docs were updated if behavior or public API changed

[Copilot]

Pull request overview

Introduces a typed DTO contract for the gateway's HTTP responses so that wire JSON, OpenAPI schemas, and x-medkit extensions are all generated from a single C++17 source-of-truth, eliminating drift between handler output and the published spec. All HTTP handler domains were migrated, the legacy XMedkit fluent builder and ~50 hand-written schema factories were removed, and integration tests now validate live responses against the served spec.

Changes:

• Add Draft202012/Draft7 jsonschema validator import with Humble fallback and new skip patterns in test_openapi_callability.test.py for schema limitations (Configuration/Trigger/CyclicSubscription).
• Add new integration test methods to assert typed x-medkit sub-schemas (XMedkitArea, XMedkitRos2, AreaListItem) are present and that live entity GET responses conform to the served OpenAPI spec (with $ref-inlining helper).
• Delete test_x_medkit.cpp since the XMedkit fluent builder is replaced by the DTO/visitor contract.

Reviewed changes

Copilot reviewed 70 out of 70 changed files in this pull request and generated no comments.

File	Description
src/ros2_medkit_integration_tests/test/features/test_openapi_callability.test.py	Adds DTO/schema presence checks, live-response-vs-spec conformance test, and skip patterns for known schema-precision gaps.
src/ros2_medkit_gateway/test/test_x_medkit.cpp	Removed; superseded by the new DTO contract test suite (test_dto_contract).

Note: the PR description states the change touches all handler domains, OpenAPI builder, and removes ~50 schema factories, but only two files are visible in this diff slice. The bulk of the migration (handlers, DTO/visitor framework, OpenAPI builder rewiring, test_dto_contract) is outside the reviewed hunks and cannot be assessed here.

[mfaferek93]

Treating null as absent here means {"data": null} on PUT configurations/{name} and PUT data/{name} now 400s. The old handlers accepted data:null as a value (body.contains("data") is true for null). Setting a parameter/value to null is legitimate and now breaks, and it isn't in the documented change list. Worth distinguishing present-but-null from absent for the json / optional value members.

[mfaferek93]

field_enum on action rejects anything outside {stop, forced_termination} at parse time, but control_execution is a virtual ScriptProvider - a plugin backend with custom actions (pause/resume/...) is now blocked at the gateway. Same pattern you reverted for ExecutionUpdateRequest.capability (71b51ae); worth a plain field() here too and letting the provider validate.

[mfaferek93]

This nests phase under x-medkit (x-medkit.phase), but the old update_status_to_json emitted a flat top-level x-medkit-phase, so clients reading x-medkit-phase break silently. Consistent with the nested-x-medkit convention, but it's a breaking wire change not in the client-observable list - same as config list items moving x-medkit-source/x-medkit-node into a nested x-medkit object. Worth adding both to the change list.

[mfaferek93]

FaultListItem is schema-only: the fault list handlers emit items verbatim from the transport (fault_handlers.cpp:339), never through JsonWriter, so this schema is an unverified claim about that wire - the drift the contract was meant to remove. It matches fault_msg_conversions today but nothing enforces it. Also several always-present fields are marked optional here, so the schema is looser than the wire. Route items through the DTO, or add a test pinning the verbatim items to this schema.

[mfaferek93]

The terminal else has no static_assert, unlike decode_value (json_reader.hpp:88) and schema_of (schema_writer.hpp:61) which both end in static_assert(sizeof(U)==0). If a DTO sentinel ever leaks (a nested DTO used in a TU that didn't see its dto_fields specialization), is_dto_v is false and this silently takes the scalar branch instead of failing to compile. Defused today by include discipline + the registry-wide instantiation, but a matching else static_assert here would make the writer fail loud like the other two visitors.

[mfaferek93]

severity_label is a plain field() so no enum reaches the schema, but the comment on line 49 and the old OpenAPI spec constrained it to INFO|WARN|ERROR|CRITICAL|UNKNOWN (same for severity_filter in logs). On a PR about schema accuracy this drops a constraint the previous spec advertised. kFaultSeverityLabelValues exists but is unused - field_enum here would restore it (response-side enum is schema-only, no request-rejection risk).