Is your feature request related to a problem?
OpenAPI Generics originally introduced generic container handling around a single canonical container model:
Over time, additional response shapes became necessary:
ServiceResponse<List<T>>
ServiceResponse<Set<T>>
and the same requirement emerged for Bring Your Own Envelope (BYOE) contracts:
ApiResponse<Page<T>>
ApiResponse<List<T>>
ApiResponse<Set<T>>
At the time, container support was effectively tied to individual container implementations rather than modeled as a platform capability.
As new container types appear, introducing support through container-specific logic becomes increasingly expensive because projection, metadata generation, OpenAPI enrichment, model reconstruction, and code generation all need container awareness.
The platform therefore lacked a dedicated abstraction for generic container handling.
Describe the solution you'd like
Introduce a first-class generic container infrastructure into OpenAPI Generics.
Instead of treating each container type as a special case, the platform should resolve containers through a dedicated container metadata model responsible for:
- container detection
- generic item extraction
- projection metadata generation
- OpenAPI vendor extension enrichment
- code generation reconstruction
- generated wrapper typing
Container support should operate through a common infrastructure regardless of envelope type.
The same mechanism should work for:
ServiceResponse<List<T>>
ServiceResponse<Set<T>>
ServiceResponse<Page<T>>
and:
ApiResponse<List<T>>
ApiResponse<Set<T>>
ApiResponse<Page<T>>
without introducing container-specific behavior throughout the pipeline.
Supported Containers
The initial implementation introduces support for:
Examples:
ServiceResponse<List<CustomerDto>>
ServiceResponse<Set<CustomerDto>>
ServiceResponse<Page<CustomerDto>>
ApiResponse<List<CustomerDto>>
ApiResponse<Set<CustomerDto>>
ApiResponse<Page<CustomerDto>>
Projected wrapper examples:
ServiceResponseListCustomerDto
ServiceResponseSetCustomerDto
ServiceResponsePageCustomerDto
ApiResponseListCustomerDto
ApiResponseSetCustomerDto
ApiResponsePageCustomerDto
All generated wrappers are reconstructed through the same container-aware infrastructure.
Architectural Outcome
Container handling is now modeled as an explicit platform capability.
Projection and reconstruction no longer depend on individual container implementations.
The platform now maintains dedicated container metadata that can be consumed consistently across:
Java Contract
↓
Projection
↓
OpenAPI Schema
↓
Vendor Extensions
↓
Code Generation
↓
Runtime Reconstruction
This establishes a deterministic container model that remains independent from any particular response envelope implementation.
Validation Coverage
The implementation is verified end-to-end through dedicated type coverage samples.
Canonical envelope validation:
ServiceResponse<T>
ServiceResponse<List<T>>
ServiceResponse<Set<T>>
ServiceResponse<Page<T>>
BYOE validation:
ApiResponse<T>
ApiResponse<List<T>>
ApiResponse<Set<T>>
ApiResponse<Page<T>>
Validation covers:
- scalar payloads
- value payloads
- enum payloads
- DTO payloads
- collection payloads
- paged payloads
- generated client reconstruction
- runtime deserialization
- consumer integration
All scenarios are exercised through producer → OpenAPI → generated client → consumer verification pipelines.
Describe alternatives you've considered
Container-specific branching
Continue implementing support independently for each container type.
While initially simpler, this approach duplicates logic across projection and reconstruction stages and becomes increasingly difficult to maintain as container support grows.
Hardcoded container expansion
Add support incrementally whenever a new container appears.
This keeps the platform functional but spreads container knowledge across multiple components and makes future evolution more expensive.
Additional context
This work establishes generic container handling as a core platform capability.
The objective is not arbitrary nested generic graph support.
The objective is deterministic support for well-defined generic container types through a shared projection and reconstruction infrastructure.
The implementation introduces:
support today while creating a foundation for future container types to participate in the same infrastructure.
Potential future candidates include:
without requiring architectural changes to the projection pipeline.
This issue represents the introduction of extensible generic container support rather than the addition of a single container type.
Is your feature request related to a problem?
OpenAPI Generics originally introduced generic container handling around a single canonical container model:
Over time, additional response shapes became necessary:
and the same requirement emerged for Bring Your Own Envelope (BYOE) contracts:
At the time, container support was effectively tied to individual container implementations rather than modeled as a platform capability.
As new container types appear, introducing support through container-specific logic becomes increasingly expensive because projection, metadata generation, OpenAPI enrichment, model reconstruction, and code generation all need container awareness.
The platform therefore lacked a dedicated abstraction for generic container handling.
Describe the solution you'd like
Introduce a first-class generic container infrastructure into OpenAPI Generics.
Instead of treating each container type as a special case, the platform should resolve containers through a dedicated container metadata model responsible for:
Container support should operate through a common infrastructure regardless of envelope type.
The same mechanism should work for:
and:
without introducing container-specific behavior throughout the pipeline.
Supported Containers
The initial implementation introduces support for:
Examples:
Projected wrapper examples:
All generated wrappers are reconstructed through the same container-aware infrastructure.
Architectural Outcome
Container handling is now modeled as an explicit platform capability.
Projection and reconstruction no longer depend on individual container implementations.
The platform now maintains dedicated container metadata that can be consumed consistently across:
This establishes a deterministic container model that remains independent from any particular response envelope implementation.
Validation Coverage
The implementation is verified end-to-end through dedicated type coverage samples.
Canonical envelope validation:
BYOE validation:
Validation covers:
All scenarios are exercised through producer → OpenAPI → generated client → consumer verification pipelines.
Describe alternatives you've considered
Container-specific branching
Continue implementing support independently for each container type.
While initially simpler, this approach duplicates logic across projection and reconstruction stages and becomes increasingly difficult to maintain as container support grows.
Hardcoded container expansion
Add support incrementally whenever a new container appears.
This keeps the platform functional but spreads container knowledge across multiple components and makes future evolution more expensive.
Additional context
This work establishes generic container handling as a core platform capability.
The objective is not arbitrary nested generic graph support.
The objective is deterministic support for well-defined generic container types through a shared projection and reconstruction infrastructure.
The implementation introduces:
support today while creating a foundation for future container types to participate in the same infrastructure.
Potential future candidates include:
without requiring architectural changes to the projection pipeline.
This issue represents the introduction of extensible generic container support rather than the addition of a single container type.