Support application-defined generic containers

[bsayli]

Problem statement

OpenAPI Generics currently provides first-class support for a fixed set of generic container contracts through the built-in container infrastructure.

Supported containers include:

List<T>
Set<T>
Page<T>

These containers participate in the complete projection and reconstruction pipeline and can be used with both the default ServiceResponse<T> envelope and custom BYOE envelopes.

However, applications often define their own generic container abstractions to represent paged, windowed, cursor-based, or domain-specific result sets.

Typical examples include:

Paging<T>
Window<T>
Slice<T>
CursorPage<T>

Although these contracts are structurally equivalent to supported containers, they are currently treated as ordinary generic objects and therefore cannot participate in generic container reconstruction.

As a result, OpenAPI Generics is limited to a predefined set of container implementations rather than supporting application-owned generic containers.

---

Proposed solution

Introduce support for application-defined generic containers through configuration.

Applications should be able to register their own generic container contracts without modifying the projection or reconstruction pipeline.

Example:

openapi-generics:
  containers:
    - type: io.example.contract.Paging
      item-property: content

    - type: io.example.contract.Window
      item-property: items

Each configured container should participate in the same lifecycle as built-in containers:

Java Contract
        ↓
Response Introspection
        ↓
Container Resolution
        ↓
OpenAPI Projection
        ↓
Vendor Extensions
        ↓
Code Generation
        ↓
Runtime Reconstruction

The existing container model should be extended rather than replaced.

Built-in containers (List, Set, and Page) and configured containers should share the same descriptor model, metadata pipeline, schema enrichment, and reconstruction process.

Application-defined containers should be validated during startup to ensure they satisfy the required generic contract.

At minimum, a configured container must:

• be a concrete generic class or record
• declare exactly one generic type parameter
• expose a configurable collection property (List<T> or Set<T>) representing the contained items

Once validated, the container should behave identically to built-in containers throughout projection and client generation.

---

Alternatives considered

Continue supporting only built-in containers

Keep support limited to List<T>, Set<T>, and Page<T>.

Rejected because many projects already own domain-specific generic containers that should not require migration to platform-defined abstractions.

Introduce dedicated support for additional container types

Add explicit implementations for Paging, Window, Slice, and other container types.

Rejected because every new container would require additional platform code and would not scale.

Infer container semantics automatically

Attempt to discover container structures using reflection without configuration.

Rejected because multiple generic classes may satisfy similar structural requirements while representing different domain semantics.

An explicit registration model is more deterministic and easier to maintain.

---

Expected impact

• Support for application-defined generic containers
• No platform changes required for future container implementations
• Unified handling of built-in and configured containers
• Improved extensibility of the projection pipeline
• Consistent OpenAPI metadata generation
• Deterministic generic reconstruction for custom container contracts
• Backward compatibility with existing List, Set, and Page support
• No changes required for existing users

---

Additional context

This feature extends the generic container infrastructure introduced in the 1.1 release.

Previously, the platform provided first-class support for a fixed set of built-in container contracts.

This proposal generalizes that infrastructure by allowing applications to contribute their own generic containers while preserving the same projection, metadata generation, code generation, and runtime reconstruction pipeline.

The result is an extensible container model in which built-in and application-defined generic containers participate uniformly without introducing container-specific branching throughout the platform.