Allow Struct Embedding with `allOf` by clarkjohnd · Pull Request #2086 · oapi-codegen/oapi-codegen

clarkjohnd · 2025-09-12T14:29:09Z

A rebase of 2 year old PR (#1295) (main code courtesy of Lahabana!) to the latest main branch with a very small tweak to error handling. This is a feature I find very useful. Also addresses #1622 (comment), where the original draft PR was linked.

Using one of my own app examples, adding x-go-allof-embed-refs: true to allOf components:

    WorkItemView:
      x-go-allof-embed-refs: true
      allOf:
      - $ref: '#/components/schemas/WorkItem'
      - type: object
        properties:
          project:
            $ref: '#/components/schemas/ProjectSummary'
          organisation:
            $ref: '#/components/schemas/OrganisationSummary'

type WorkItemView struct {
    // all fields duplicated from root component WorkItem
    // ...
    // ...
    Organisation *OrganisationSummary `json:"organisation,omitempty"`
    Project      *ProjectSummary      `json:"project,omitempty"`
}

to:

type WorkItemView struct {
    // Embedded struct due to allOf(#/components/schemas/WorkItem)
    WorkItem `yaml:",inline"`
    // Embedded fields due to inline allOf schema
    Organisation *OrganisationSummary `json:"organisation,omitempty"`
    Project      *ProjectSummary      `json:"project,omitempty"`
}

This helps build reusable functions for "extendable" types - e.g. I have a function to populate WorkItem - now if I extend work item to add other fields for other API paths (like above example), I can reuse the same function to manage the WorkItem nested struct, rather than rebuilding an entire new function for the extended type.

This is useful when working with extending APIs Signed-off-by: Charly Molter <[email protected]>

kusari-inspector · 2025-09-12T14:29:35Z

Kusari Analysis Results:

✅ No Flagged Issues Detected
All values appear to be within acceptable risk parameters.

No pinned version dependency changes, code issues or exposed secrets detected!

Note

View full detailed analysis result for more information on the output and the checks that were run.

@kusari-inspector rerun - Trigger a re-analysis of this PR
@kusari-inspector feedback [your message] - Send feedback to our AI and team
See Kusari's documentation for setup and configuration.
Commit: 5389038, performed at: 2025-09-12T14:29:19Z

Found this helpful? Give it a 👍 or 👎 reaction!

marcoabreu · 2025-12-10T14:27:54Z

Would love to see this merged, good job!

mromaszewicz · 2026-02-24T18:28:05Z

@greptileai

greptile-apps · 2026-02-24T18:30:21Z

Greptile Summary

This PR adds support for struct embedding in allOf compositions via the x-go-allof-embed-refs: true extension. The implementation allows referenced schemas to be embedded as structs rather than having their fields duplicated, enabling better code reuse for extendable types.

Key Changes:

Added x-go-allof-embed-refs extension support in extension.go with a helper function to read the boolean value
Modified schema merging logic in merge_schemas.go to conditionally generate embedded structs when the extension is enabled
Added validation to prevent overlapping fields between sibling schemas and modifications to required fields outside their own schema when using embedding
Added comprehensive test cases to verify the feature works correctly

Potential Issue:

The test case in embed-openapi.yaml appears to have overlapping FirstName fields between PersonProperties and FirstName schemas in the Person allOf, which should trigger validation errors according to the implementation

Confidence Score: 3/5

This PR adds a useful feature but has a test case that may not align with validation logic
The core implementation is solid with proper error handling and validation checks. However, the test schema appears to have overlapping fields that should fail validation based on the implemented checks. This needs verification that either the test is correct or the validation logic needs adjustment.
internal/test/all_of/embed-openapi.yaml needs verification - check if the overlapping FirstName field is intentional or if it should be removed from one of the schemas

Important Files Changed

Filename	Overview
pkg/codegen/extension.go	Added new extension constant and helper function for `x-go-allof-embed-refs` feature
pkg/codegen/merge_schemas.go	Core implementation of embedding feature with validation for overlapping fields and required field modifications
pkg/codegen/schema.go	Added call to `ReadExtGoAllOfEmbedRefs` to enable the feature when processing `allOf` schemas
internal/test/all_of/embed-openapi.yaml	Test schema with potential overlapping `FirstName` field in `Person` allOf that may violate validation rules

_{Last reviewed commit: b109546}

greptile-apps

_{10 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-02-24T18:30:26Z

+      allOf:
+        - $ref: "#/components/schemas/PersonProperties"
+        - required: [ FirstName, LastName ]
+        - $ref: "#/components/schemas/FirstName"


Potential overlapping field issue: both PersonProperties (line 34) and FirstName (line 36) define a FirstName property. The validation logic in merge_schemas.go:215-219 checks for overlapping fields and should reject this when x-go-allof-embed-refs: true is set. Verify that this test case generates correctly or if it needs to be updated.

mromaszewicz · 2026-02-24T18:35:27Z

This is a very tricky change, despite seeming simple, and I think we need lots more testing to ensure it doesn't break behavior.

When you embed structs, you also embed their methods.

In your example, say, WorkItem is a complex schema with a complex structure that requires implementing the json.Marshaler and json.Unmarshaler interfaces, which we do automatically.

Due to this embedding, when the json library is doing its unarshaling, it will find that WorkItemView has JSON marshaling specializations, and it will call those, so it will attempt to unmarshal WorkItemView using WorkItem.UnmarshalJSON.

I've hit these problems before.

Dynamic typing in a stricly typed language is quite hard, and allOf/anyOf/oneOf has been the most difficult thing to support in oapi-codegen.

lahabana and others added 3 commits September 11, 2025 22:49

add option x-go-allof-embed-refs

7dc35d7

This is useful when working with extending APIs Signed-off-by: Charly Molter <[email protected]>

identify overlapping field in error

7e63712

Fix base error change

5389038

clarkjohnd requested a review from a team as a code owner September 12, 2025 14:29

Merge branch 'main' into xEmbedRef

b109546

greptile-apps Bot reviewed Feb 24, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Allow Struct Embedding with `allOf`#2086

Allow Struct Embedding with `allOf`#2086
clarkjohnd wants to merge 4 commits into
oapi-codegen:mainfrom
clarkjohnd:xEmbedRef

clarkjohnd commented Sep 12, 2025 •

edited

Loading

Uh oh!

kusari-inspector Bot commented Sep 12, 2025

Uh oh!

marcoabreu commented Dec 10, 2025

Uh oh!

mromaszewicz commented Feb 24, 2026

Uh oh!

greptile-apps Bot commented Feb 24, 2026

Important Files Changed

Uh oh!

greptile-apps Bot left a comment

Uh oh!

greptile-apps Bot Feb 24, 2026

Uh oh!

mromaszewicz commented Feb 24, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

clarkjohnd commented Sep 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kusari-inspector Bot commented Sep 12, 2025

Kusari Analysis Results:

Uh oh!

marcoabreu commented Dec 10, 2025

Uh oh!

mromaszewicz commented Feb 24, 2026

Uh oh!

greptile-apps Bot commented Feb 24, 2026

Greptile Summary

Confidence Score: 3/5

Important Files Changed

Uh oh!

greptile-apps Bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

mromaszewicz commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

clarkjohnd commented Sep 12, 2025 •

edited

Loading

mromaszewicz commented Feb 24, 2026 •

edited

Loading