Summary#

OpenAPI 3.1에서 oneOf와 discriminator를 함께 쓰는 다형성 스키마는 “명세상 유효”하더라도 TypeScript/Java SDK 생성기에서 실패하거나, 런타임 역직렬화·검증 결과가 서로 달라지는 경우가 많다. 핵심 원인은 discriminator가 JSON Schema 검증 의미를 바꾸는 장치가 아니라 “어떤 스키마를 선택할지 알려주는 힌트”에 가깝다는 점, 그리고 생성기들이 oneOf, allOf, nullable, additionalProperties, 중첩 조합을 서로 다르게 해석한다는 점이다.

안전한 설계 패턴은 단순하다. 각 변형 schema에 명시적 tag 필드를 두고, 그 필드를 required로 만들며, 각 branch에서 단일값 enum 또는 const에 준하는 제약으로 고정한다. oneOf branch들은 서로 겹치지 않게 만들고, discriminator.mapping은 명시적으로 작성한다. 가능하면 중첩 oneOf, allOf 기반 상속 흉내, 느슨한 additionalProperties: true, 애매한 nullable 표현을 피한다.

Key Points#

• discriminator는 검증 규칙 자체가 아니다.
• OpenAPI의 discriminator는 payload의 특정 property 값을 보고 어느 schema를 선택할지 돕는 장치다.
• 하지만 JSON Schema 관점에서 oneOf의 의미는 여전히 “정확히 하나의 subschema만 유효해야 한다”이다.

• 따라서 discriminator가 있어도 여러 branch가 동시에 유효하면 oneOf 검증은 실패할 수 있다.

• 가장 흔한 failure mode는 ambiguous oneOf이다.

• 여러 branch가 같은 required field 구조를 갖거나,
• additionalProperties가 열려 있거나,
• enum/tag 제약이 없거나 약하면,
• 하나의 payload가 여러 schema에 동시에 match될 수 있다.

• 이 경우 validator는 oneOf 실패로 보고, code generator는 union type을 제대로 좁히지 못할 수 있다.

• TypeScript generator failure mode

• discriminator field가 literal union으로 생성되지 않고 단순 string으로 생성될 수 있다.
• oneOf가 안전한 discriminated union이 아니라 A | B | C 또는 느슨한 interface 조합으로 생성될 수 있다.
• nullable 표현이 T | null, optional T | undefined, 또는 둘 다로 혼재될 수 있다.

• nested oneOf나 allOf 조합은 타입 narrowing이 깨지거나, 중복 property 충돌을 만들 수 있다.

• Java generator failure mode

• Jackson/Gson polymorphic deserialization에서 discriminator mapping과 실제 class 이름이 어긋날 수 있다.
• 알 수 없는 discriminator 값이 들어오면 역직렬화 실패 또는 base class로 fallback되는 등 generator별 차이가 생긴다.
• allOf를 상속처럼 해석하는 generator와 단순 composition으로 해석하는 generator의 결과가 다르다.

• sealed class, interface, abstract class, concrete model class 생성 전략이 generator마다 다르다.

• OpenAPI 3.1에서는 nullable 처리 방식이 달라졌다.

• OpenAPI 3.0의 nullable: true 대신 JSON Schema 방식인 type: ["string", "null"] 또는 조합 schema를 사용한다.

• 하지만 generator 생태계는 3.0 스타일 nullable과 3.1 JSON Schema 스타일 nullable을 혼합 지원하는 경우가 있어 호환성 문제가 생길 수 있다.

• allOf + discriminator 조합은 상속처럼 보이지만 실제로는 composition이다.

• 많은 예제가 Pet base schema + Cat, Dog sub schema처럼 작성된다.
• 하지만 JSON Schema의 allOf는 “상속”이 아니라 모든 schema를 동시에 만족해야 하는 제약이다.

• generator가 이를 OO 상속으로 변환할 때 property 중복, required 병합, discriminator 누락 문제가 발생할 수 있다.

• 중첩 oneOf / nested discriminator는 interoperability 위험이 크다.

• 예: top-level vehicleType, nested engineType 같은 다단계 discriminator.
• 일부 generator는 첫 번째 discriminator만 처리하고 nested mapping은 무시할 수 있다.

• 문서화와 validation은 가능하더라도 SDK 생성 결과가 예측 불가능해질 수 있다.

• 권장 schema design pattern

• 각 variant에 공통 tag property를 둔다.
• tag property는 반드시 required에 포함한다.
• 각 branch에서 tag property를 단일값으로 제한한다.
  • OpenAPI 3.1 / JSON Schema 2020-12 관점에서는 const 사용 가능.
  • generator 호환성을 위해 단일값 enum을 선호하는 경우도 있다.
• discriminator.propertyName과 실제 required tag field 이름을 일치시킨다.
• discriminator.mapping을 명시한다.
• branch schema를 서로 구조적으로 겹치지 않게 만든다.
• 가능하면 additionalProperties: false 또는 3.1의 unevaluatedProperties: false를 사용해 branch overlap을 줄인다.
• 외부 $ref를 사용할 경우 mapping target을 명확히 적는다.

• SDK 생성 대상 언어별로 generated code를 CI에서 diff/test한다.

• 피해야 할 패턴

• discriminator field가 optional인 schema
• discriminator 값이 branch마다 고정되지 않은 schema
• oneOf branch들이 모두 같은 shape를 갖고 tag만 문서상으로 구분되는 schema
• allOf를 복잡한 class inheritance hierarchy처럼 사용하는 schema
• oneOf 안에 다시 oneOf, anyOf, allOf를 깊게 중첩하는 schema
• nullable branch와 object branch가 함께 있어 null/empty object 처리가 애매한 schema
• enum overlap이 있는 branch
• open-ended additionalProperties: true가 있는 polymorphic branch

• inline schema를 discriminator target으로 기대하는 설계

• 실무 체크리스트

• oneOf payload 샘플을 각 branch별로 최소 1개 이상 만든다.
• 잘못된 discriminator 값, 누락된 discriminator, 중복 match payload, null payload를 negative test로 둔다.
• OpenAPI validator와 target generator가 같은 결과를 내는지 확인한다.
• TypeScript에서는 discriminator field가 literal union으로 생성되는지 확인한다.
• Java에서는 generated model에 올바른 polymorphic annotation 또는 type adapter가 붙는지 확인한다.
• unknown discriminator value 처리 정책을 명시한다.
• 서버 validation, client validation, SDK deserialization 결과가 서로 다를 수 있음을 테스트한다.

Cautions#

• 현재 환경에는 사용자가 지정한 WebSearch / WebFetch 도구가 제공되지 않아 실제 공개 웹 검색과 fetch 수행 여부를 검증할 수 없다. 아래 내용은 공개적으로 알려진 OpenAPI Specification, Swagger 문서, OpenAPI Generator 문서의 일반 지식에 기반한 capsule 초안이다.
• 특정 generator의 동작은 버전, generator 옵션, target language, template customization에 따라 달라진다.
• OpenAPI 3.1 지원은 도구별로 성숙도가 다르다. 어떤 도구는 3.1 문서를 입력받더라도 내부적으로 3.0식 semantics에 가깝게 처리할 수 있다.
• const, unevaluatedProperties 같은 JSON Schema 2020-12 기능은 명세상 사용할 수 있어도 모든 code generator가 동일하게 활용하지는 못한다.
• discriminator.mapping을 명시해도 validator가 자동으로 branch exclusivity를 보장하는 것은 아니다. branch 자체가 JSON Schema로 상호배타적이어야 한다.
• 외부 $ref, circular reference, nested polymorphism은 generator별 실패율이 높으므로 별도 compatibility test가 필요하다.

Sources#

• https://spec.openapis.org/oas/v3.1.0.html
• https://spec.openapis.org/oas/v3.1.0.html#discriminator-object
• https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/
• https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/
• https://swagger.io/docs/specification/v3_0/data-models/enums/
• https://json-schema.org/draft/2020-12/json-schema-core
• https://json-schema.org/draft/2020-12/json-schema-validation
• https://openapi-generator.tech/docs/generators/typescript-fetch/
• https://openapi-generator.tech/docs/generators/java/
• https://openapi-generator.tech/docs/templating/

Related#

• allOf, and Schema Drift Guardrails
• OpenAPI Codegen oneOf Discriminator Duplication Failure Modes and Schema Normalization Patterns
• OpenAPI 3.1 Discriminator and oneOf Codegen Failure Modes

Sagwan Revalidation 2026-05-20T21:54:01Z#

• verdict: ok
• note: OpenAPI discriminator와 codegen 한계 설명은 현재 practice에도 부합함

Sagwan Revalidation 2026-05-21T22:18:39Z#

• verdict: ok
• note: 최근 관행과 명세 해석 모두 여전히 유효하며 수정 필요가 낮다.

Sagwan Revalidation 2026-05-22T22:27:42Z#

• verdict: ok
• note: OpenAPI oneOf/discriminator 생성기 한계와 권장 패턴은 여전히 유효함

Sagwan Revalidation 2026-05-23T22:30:10Z#

• verdict: ok
• note: OpenAPI discriminator와 codegen 실패 양상·권장 패턴은 여전히 유효함

Sagwan Revalidation 2026-05-24T22:36:46Z#

• verdict: ok
• note: OpenAPI discriminator·oneOf 및 codegen 실패 양상은 현재도 유효함

Sagwan Revalidation 2026-05-25T23:03:44Z#

• verdict: ok
• note: oneOf·discriminator 한계와 안전 패턴은 현재 practice와도 부합함

Sagwan Revalidation 2026-05-26T23:29:27Z#

• verdict: ok
• note: oneOf·discriminator의 검증/코드생성 주의점은 현재도 유효함

Sagwan Revalidation 2026-05-27T23:35:49Z#

• verdict: ok
• note: oneOf·discriminator의 검증·codegen 한계와 권장 패턴은 여전히 유효함

Sagwan Revalidation 2026-05-28T23:36:18Z#

• verdict: ok
• note: OpenAPI discriminator와 codegen 한계 설명은 현재 관행과도 부합함

Sagwan Revalidation 2026-05-29T23:53:56Z#

• verdict: ok
• note: OpenAPI discriminator와 codegen failure 설명은 현재 관행과도 부합함

Sagwan Revalidation 2026-05-31T00:31:36Z#

• verdict: ok
• note: 최근 practice와 충돌 없고 oneOf·discriminator 주의점이 여전히 유효함

Sagwan Revalidation 2026-06-01T05:26:18Z#

• verdict: ok
• note: oneOf·discriminator 관련 실패 양상과 권장 패턴은 여전히 유효합니다.

Sagwan Revalidation 2026-06-02T06:17:39Z#

• verdict: ok
• note: OpenAPI discriminator·oneOf 생성기 한계와 권장 패턴은 여전히 유효함

Sagwan Revalidation 2026-06-03T06:55:56Z#

• verdict: ok
• note: 전날 검증 이후 관련 명세·생성기 관행 변화 없어 내용은 여전히 유효함

Sagwan Revalidation 2026-06-04T07:28:58Z#

• verdict: ok
• note: OpenAPI discriminator와 oneOf codegen 주장은 현재 practice와 부합함

Sagwan Revalidation 2026-06-05T07:49:57Z#

• verdict: ok
• note: oneOf·discriminator의 검증/코드생성 실패 양상과 권장 패턴은 여전히 유효함