[Proposal / Idea] Explicit Template Metadata for Generic Schema Patterns in OpenAPI

[Falco94]

TL;DR

OpenAPI currently lacks a clear way to describe generic or template-like schema structures such as Response<T> or Page<T>.

While JSON Schema dynamic references ($dynamicRef) technically allow substitution patterns similar to generics, they do not provide explicit metadata describing template parameters or template instantiations. As a result, tooling cannot reliably detect or reconstruct generic structures.

This proposal suggests introducing two optional schema keywords:

• templateParameters
• instantiates

These keywords allow tooling to detect template definitions and template instantiations while remaining fully compatible with JSON Schema and existing OpenAPI tooling.

The proposal is additive, language-neutral, and could initially be introduced as vendor extensions.

---

Context

I have been working with OpenAPI for several years in the context of API tooling and SDK generation.

While implementing client generation workflows, I repeatedly encountered difficulties modeling generic or template-like structures such as Response<T> or Page<T> in OpenAPI specifications.

This proposal represents an attempt to describe a possible approach for modeling such structures in a way that remains compatible with existing OpenAPI and JSON Schema mechanisms.

I may be missing context from previous design discussions or decisions made by the OpenAPI TSC or JSON Schema working group. If so, I would very much appreciate pointers or corrections.

---

Table of Contents

• Background
• Prior Discussion
• Goal
• Real-World Example
• Current OpenAPI Representation
• Proposed Template Metadata
• Template Definition
• Template Instantiation
• Template Instantiation Algorithm
• Allowed Argument Types
• Nested Templates
• Recursive Instantiations
• Interaction with $ref
• JSON Schema Compatibility
• Substitution Mechanism
• Compatibility Strategy
• Possible Evolution Path
• Non-Goals
• Prior Art
• Conclusion

---

Background

Generic or template-based data structures are widely used in modern APIs and programming languages.

Examples include:

• Response<T>
• Page<T>
• Envelope<T>
• Dictionary<TKey, TValue>
• Result<TValue, TError>

These patterns appear across many languages including:

• C#
• Java / Kotlin
• TypeScript
• Rust
• C++ (templates)

However, when APIs using these patterns are described in OpenAPI today, the generic structure is typically materialized into concrete schemas such as:

ResponseOfBook
ResponseOfUser
PageOfBook

While this representation is valid and interoperable, it introduces several limitations:

• structural relationships between schemas are lost
• nested generics become opaque
• SDK generators often produce many wrapper types
• template structure cannot be reconstructed by tooling

For example, a type such as:

Response<Page<Book>>

is often flattened into:

ResponseOfPageOfBook

which loses structural information.

---

Prior Discussion

Generic wrapper structures and template-like patterns have been discussed multiple times in the OpenAPI community.

Relevant discussions include:

#3601
Recommend describing templates / generic types using $dynamicRef

#957
Representing Java generics in Swagger/OpenAPI

#555
Envelope / wrapper schema patterns

Since OpenAPI 3.1 aligned with JSON Schema 2020-12, the specification includes support for dynamic references:

• $dynamicRef
• $dynamicAnchor

These allow substitution patterns similar to generics.

A detailed explanation is available here:

https://json-schema.org/blog/posts/dynamicref-and-generics/

However, $dynamicRef only enables schema substitution, not explicit template semantics.

It does not describe:

• template parameters
• template instantiations
• template families
• relationships between template instances

---

Goal

The goal of this proposal is not to replace $dynamicRef, but to introduce explicit metadata that allows tools to detect template structures.

Design goals:

• additive extension
• compatibility with JSON Schema
• language-neutral modeling
• deterministic template instantiation
• backwards compatibility

---

Real-World Example

Consider a simple Book API.

Endpoints:

GET /books
GET /books/{id}
GET /books/{id}/exists

Typical return types:

Response<Page<Book>>
Response<Book>
Response<boolean>

---

Current OpenAPI Representation

Today these might be described as:

components:
  schemas:

    Book:
      type: object
      properties:
        id:
          type: string
        title:
          type: string

    PageOfBook:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Book"
        totalCount:
          type: integer

    ResponseOfPageOfBook:
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: "#/components/schemas/PageOfBook"

Although valid, the structural relationship between these schemas is not machine-detectable.

---

Proposed Template Metadata

Introduce two schema properties:

templateParameters
instantiates

These describe template definitions and template instantiations.

---

Template Definition

Example template schema:

Response:
  templateParameters:
    - T
  type: object
  properties:
    success:
      type: boolean
    errorCode:
      type: integer
    data:
      $dynamicRef: "#T"

Semantically equivalent to:

Response<T>

Another template:

Page:
  templateParameters:
    - T
  type: object
  properties:
    items:
      type: array
      items:
        $dynamicRef: "#T"
    totalCount:
      type: integer

Equivalent to:

Page<T>

---

Template Instantiation

Concrete schemas bind template parameters.

PageOfBook:
  instantiates:
    template: "#/components/schemas/Page"
    arguments:
      T: "#/components/schemas/Book"

ResponseOfPageOfBook:
  instantiates:
    template: "#/components/schemas/Response"
    arguments:
      T: "#/components/schemas/PageOfBook"

ResponseOfBook:
  instantiates:
    template: "#/components/schemas/Response"
    arguments:
      T: "#/components/schemas/Book"

ResponseOfBoolean:
  instantiates:
    template: "#/components/schemas/Response"
    arguments:
      T:
        type: boolean

---

Template Instantiation Algorithm

1. Resolve the referenced template schema.

2. Validate that all template parameters are bound exactly once.

3. Traverse the template schema recursively.

4. For each $dynamicRef referencing a template parameter:

   replace the reference with the corresponding argument schema.

5. Replacement MUST occur for all occurrences of the parameter.

Traversal includes:

• properties
• items
• allOf
• anyOf
• oneOf
• not

The result MUST be a fully materialized schema.

---

Allowed Argument Types

Template arguments MUST be either:

• a Schema Object
• a Reference Object

Example:

T: "#/components/schemas/Book"

or:

T:
  type: boolean

---

Nested Templates

Template arguments MAY themselves be template instantiations.

Example:

Response<Page<Book>>

---

Recursive Instantiations

Recursive instantiations MAY occur.

Example:

RecursivePage:
  instantiates:
    template: "#/components/schemas/Page"
    arguments:
      T: "#/components/schemas/RecursivePage"

Such recursion follows existing JSON Schema recursion rules.

---

Interaction with $ref

A schema MUST NOT contain both:

$ref
instantiates

because $ref replaces the entire schema.

---

JSON Schema Compatibility

JSON Schema allows unknown keywords unless restricted by a vocabulary.

Therefore the following keywords can safely be ignored by validators:

templateParameters
instantiates

Tools that do not recognize these keywords can still process the schema.

---

Substitution Mechanism

This proposal does not mandate $dynamicRef.

It only introduces metadata describing template structure.

Implementations MAY rely on:

• $dynamicRef
• $ref
• internal substitution mechanisms

when materializing templates.

---

Compatibility Strategy

For backwards compatibility, template instantiations SHOULD resolve to a fully materialized schema.

Tools that do not support template metadata MAY:

1. ignore it
2. operate on the materialized schema

---

Possible Evolution Path

A practical adoption path could be:

1. introduce vendor extensions

x-templateParameters
x-instantiates

2. experiment with tooling
3. gather community feedback
4. propose standardization through the OpenAPI TSC process

---

Non-Goals

This proposal intentionally does not attempt to model:

• language-specific type systems
• variance rules
• advanced generic constraints
• language-specific semantics

The goal is only to represent template structure in a language-neutral way.

---

Prior Art

Generic structures are common in many ecosystems:

• language generics (C#, Java, Rust)
• C++ templates
• GraphQL wrappers
• Protocol Buffers message composition

---

Conclusion

OpenAPI already provides the technical mechanism for schema substitution via JSON Schema dynamic references.

Introducing explicit template metadata would allow tooling to:

• detect template families
• reconstruct nested generics
• generate more accurate SDKs
• reduce schema duplication

while remaining fully compatible with existing tooling and specifications.