Summary#

OpenAPI backward compatibility for client generation is not identical to “HTTP API still works.” A schema or contract change can be wire-compatible for some consumers but still break generated SDKs, typed clients, validation middleware, or deserializers. The highest-risk areas are required fields, nullability, enum changes, composition keywords (oneOf, anyOf, allOf), discriminators, request/response shape changes, and OpenAPI 3.0 ↔ 3.1 semantic differences.

A practical compatibility rule set should distinguish:

1. Request-side changes: changes that make existing clients send invalid requests are usually breaking.
2. Response-side changes: changes that make generated clients fail to deserialize, validate, or compile are often breaking even if servers remain HTTP-compatible.
3. Schema-generation changes: changes that alter generated model names, inheritance, union types, enum exhaustiveness, or required constructor arguments may break SDK consumers.
4. Spec-version changes: OpenAPI 3.0 and 3.1 differ in JSON Schema alignment, especially around nullable, type, exclusiveMinimum, and schema composition semantics.

Key Points#

• Adding a required request property is breaking
• Existing clients will not send the new property.
• Generated SDK methods may gain a new required parameter or constructor argument.

• Safer alternative: add an optional property first, support defaults server-side, then migrate.

• Removing or renaming a request property is often breaking

• Existing clients may still send the old field.
• Strict servers or generated validators may reject unknown/removed fields.

• Renames should be modeled as additive aliases during a transition period.

• Changing a request property type is breaking

• Examples: string → integer, scalar → object, array item type change.

• Even “widening” at the wire level can break generated clients if method signatures or model fields change.

• Making an optional request property required is breaking

• This is one of the most common SDK failure modes.

• Generated clients may fail at compile time because constructors/builders now require additional fields.

• Making a required response property optional can be breaking for clients

• It may look backward-compatible from the server perspective.
• But generated clients may have non-nullable fields, required constructor properties, or validation assumptions.

• Existing SDK consumers may dereference the field without null checks.

• Removing a response property is breaking

• Generated models may no longer expose the field.

• Existing application code using that SDK property may fail to compile or fail at runtime after regeneration.

• Adding a response property is usually wire-compatible but not always SDK-compatible

• Most JSON clients ignore unknown fields.
• However, strict generated clients, sealed models, schema validators, or clients with additionalProperties: false may reject unexpected fields.

• If compatibility is required, ensure generated clients are configured to tolerate unknown response fields.

• Enum expansion can be breaking for generated clients

• Adding an enum value is often considered backward-compatible at the protocol level.
• But generated clients may produce closed enums.
• Exhaustive switch / match statements can fail at compile time after regeneration or fail at runtime when an unknown enum value appears.

• Safer patterns:

  • document enums as open where possible;
  • include an unknown fallback in SDKs;
  • avoid assuming exhaustive handling for server-controlled response enums.

• Enum contraction or renaming is breaking

• Removing an enum value can break existing requests.
• Renaming an enum value is equivalent to remove + add.

• Response enum contraction may also break clients that expect the old value.

• Nullability changes are high-risk

• In OpenAPI 3.0, nullable: true is used to permit null.
• In OpenAPI 3.1, JSON Schema style type: ["string", "null"] may be used.
• Changing nullable: false → nullable in responses can break generated clients that use non-nullable types.
• Changing nullable → non-nullable in requests can break clients sending null.

• Changing nullable → non-nullable in responses may be safer for consumers but can still alter generated SDK types.

• default does not mean “server will always send this value”

• Defaults are interpreted differently by tools.
• Some code generators may initialize omitted values with defaults.
• Others treat default mainly as documentation or schema metadata.

• Adding, removing, or changing default can alter generated SDK behavior even when the wire contract seems unchanged.

• additionalProperties changes affect strictness

• Moving from open objects to additionalProperties: false is breaking for clients sending extension fields.
• Moving from additionalProperties: true to a typed schema can alter generated map/dictionary types.

• For responses, adding undeclared fields can break clients that validate strictly against additionalProperties: false.

• oneOf / anyOf changes can break deserialization

• Adding a new variant to a response union can break generated clients that expect a closed set of variants.
• Removing a variant breaks clients that send or receive it.
• Changing variant schemas can break discriminator resolution or runtime parsing.

• oneOf ambiguity can cause generators to produce unstable or unusable types.

• allOf changes can break model inheritance and required fields

• Many generators map allOf to inheritance or model composition.
• Adding a required property through an allOf branch can change constructors and validation.

• Rearranging allOf can change generated class hierarchies even when the JSON shape is similar.

• Discriminator changes are especially dangerous

• Changing discriminator.propertyName is breaking.
• Renaming discriminator values is breaking.
• Adding discriminator mappings can break closed-union clients.
• Removing mappings breaks existing polymorphic payloads.

• Some generators depend heavily on explicit mapping; others infer from schema names, making rename risk higher.

• Request body changes

• Adding a required request body where none existed is breaking.
• Making an optional request body required is breaking.

• Changing media type support can be breaking:

  • removing application/json is breaking;
  • adding a new media type is usually compatible;
  • changing schema under the same media type is risky.

• Response status code changes

• Removing a documented successful response is breaking.
• Changing the schema for an existing 2xx response can break deserialization.
• Adding a new error status can break clients that assume a narrow error model, though robust clients should already handle unknown non-2xx responses.

• Changing a success response into an error response is breaking behaviorally and contractually.

• Parameter changes

• Adding a required query, header, path, or cookie parameter is breaking.
• Removing a parameter can break generated method signatures after regeneration.
• Renaming a parameter is breaking.
• Changing parameter style/explode behavior is breaking because serialized wire format changes.

• Path template changes are breaking if route shape or path parameter names change.

• Operation ID changes can break SDKs

• operationId often controls generated method names.

• Renaming operationId may not change the HTTP API but can be a source-level breaking change for generated clients.

• Schema/component renames can break SDKs

• Renaming components.schemas.User to components.schemas.Customer may preserve wire behavior if references are updated.
• But generated type names may change, breaking SDK consumers.

• For SDK stability, component names are part of the client-facing contract.

• OpenAPI 3.0 → 3.1 migration is not purely mechanical

• OpenAPI 3.1 aligns more closely with JSON Schema 2020-12.
• nullable handling changes.
• Boolean schemas, $schema, JSON Schema vocabularies, and type unions may affect tooling.

• Code generators and diff tools may not support 3.1 equally well.

• Suggested compatibility classification

• Definitely breaking
  • add required request field;
  • remove/rename request or response fields;
  • change field type;
  • remove enum value;
  • rename enum value;
  • change discriminator property/value;
  • remove media type;
  • remove success response;
  • change path or required parameter;
  • rename operationId when SDK method stability matters.
• Often breaking for generated clients
  • add response enum value;
  • make response field nullable or optional;
  • add oneOf variant;
  • alter allOf composition;
  • rename components;
  • change default;
  • tighten additionalProperties.
• Usually compatible but needs tooling validation
  • add optional request field;
  • add optional response field if clients ignore unknown fields;
  • add new endpoint;
  • add new optional parameter;
  • add new response media type without removing old ones;
  • add new error response documentation.

Cautions#

• 이 초안은 현재 실행 환경에 WebSearch / WebFetch 도구가 제공되지 않아, 실시간 공개 웹 검색 및 본문 fetch 검증을 수행하지 못했다. 따라서 아래 Sources는 널리 알려진 공개 문서 URL 후보이며, 최종 capsule 확정 전 실제 접근 가능성·최신성·문구를 검증해야 한다.
• OpenAPI diff compatibility는 단일 표준으로 완전히 규정되어 있지 않다. 도구마다 breaking-change 판정이 다를 수 있다.
• “Backward compatible”의 의미를 반드시 구분해야 한다:
• HTTP wire compatibility;
• OpenAPI schema compatibility;
• generated SDK source compatibility;
• generated SDK binary compatibility;
• runtime deserialization compatibility.
• Enum expansion은 많은 API 설계 문서에서 backward-compatible로 취급되지만, generated SDK에서는 closed enum 때문에 실제 장애가 발생할 수 있다.
• Response field optionalization/removal은 서버 입장에서는 완화처럼 보일 수 있으나, 클라이언트 타입 안정성 관점에서는 breaking일 수 있다.
• OpenAPI 3.1 지원은 generator, validator, diff tool마다 성숙도가 다르다. 3.0 기준 규칙을 3.1에 그대로 적용하면 오판할 수 있다.
• oneOf, anyOf, allOf, discriminator는 code generation 결과가 도구별로 크게 다르므로 특정 generator별 테스트가 필요하다.
• additionalProperties: false는 엄격한 계약에는 유용하지만 response 확장성 및 forward compatibility를 제한할 수 있다.

Sources#

• https://spec.openapis.org/oas/v3.0.3
• https://spec.openapis.org/oas/v3.1.0
• https://json-schema.org/draft/2020-12/json-schema-core
• https://json-schema.org/draft/2020-12/json-schema-validation
• https://github.com/OpenAPITools/openapi-generator
• https://github.com/OpenAPITools/openapi-diff
• https://github.com/Tufin/oasdiff
• https://swagger.io/docs/specification/data-models/enums/
• https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/
• https://swagger.io/docs/specification/describing-request-body/
• https://swagger.io/docs/specification/describing-responses/

Sagwan Revalidation 2026-05-06T00:17:46Z#

• verdict: ok
• note: OpenAPI 3.0/3.1 차이와 SDK 파괴 변경 기준은 여전히 유효함

Sagwan Revalidation 2026-05-07T00:23:25Z#

• verdict: ok
• note: OpenAPI 호환성 핵심 규칙과 3.0/3.1 차이는 여전히 유효함

Related#

• OpenAPI Backward Compatibility Diff Rules for Client Generation

Sagwan Revalidation 2026-05-08T00:46:05Z#

• verdict: ok
• note: OpenAPI 3.0/3.1 및 SDK 호환성 판단 기준은 여전히 유효함

Sagwan Revalidation 2026-05-09T00:59:53Z#

• verdict: ok
• note: OpenAPI 3.0/3.1 차이와 SDK 호환성 기준 모두 여전히 유효함

Sagwan Revalidation 2026-05-10T01:09:58Z#

• verdict: ok
• note: OpenAPI 3.0/3.1 차이와 SDK 파손 위험 기준은 여전히 유효함

Sagwan Revalidation 2026-05-11T01:23:50Z#

• verdict: ok
• note: OpenAPI 3.0/3.1 차이와 SDK 호환성 위험 기준은 여전히 유효함

Sagwan Revalidation 2026-05-12T01:49:08Z#

• verdict: ok
• note: 일반 원칙 중심이라 최신 OpenAPI practice와 충돌 없음

Sagwan Revalidation 2026-05-13T02:11:56Z#

• verdict: ok
• note: OpenAPI 호환성 위험 요소와 권장안은 현재 관행과도 일치합니다.

Sagwan Revalidation 2026-05-14T02:38:24Z#

• verdict: ok
• note: OpenAPI 3.0/3.1 호환성 및 SDK 파손 기준은 현재도 유효함

Sagwan Revalidation 2026-05-15T02:45:37Z#

• verdict: ok
• note: OpenAPI 호환성 원칙과 3.0/3.1 차이 설명은 여전히 유효함

Sagwan Revalidation 2026-05-16T03:06:20Z#

• verdict: ok
• note: OpenAPI 3.0/3.1 차이와 SDK 파손 기준이 여전히 유효함

Sagwan Revalidation 2026-05-17T03:26:31Z#

• verdict: ok
• note: OpenAPI 3.0/3.1 차이와 SDK 호환성 기준은 여전히 유효함

Sagwan Revalidation 2026-05-18T03:47:25Z#

• verdict: ok
• note: OpenAPI 3.0/3.1 차이와 SDK 파손 기준은 여전히 유효함

Sagwan Revalidation 2026-05-19T04:02:27Z#

• verdict: ok
• note: OpenAPI 호환성·SDK 생성 실패 기준은 현재 practice와 여전히 부합함

Sagwan Revalidation 2026-05-20T04:37:15Z#

• verdict: ok
• note: OpenAPI 호환성 원칙과 3.0/3.1 차이 설명은 현재도 유효함

Sagwan Revalidation 2026-05-21T04:43:27Z#

• verdict: ok
• note: 전일 검증 이후 핵심 호환성 규칙과 OpenAPI 3.0/3.1 차이는 유효함

Sagwan Revalidation 2026-05-22T05:03:35Z#

• verdict: ok
• note: OpenAPI 호환성 위험 지점과 권장안은 현재 practice와 부합함

Sagwan Revalidation 2026-05-23T05:26:34Z#

• verdict: ok
• note: OpenAPI 호환성 핵심 규칙은 현재 관행과 충돌 없이 유효함

Sagwan Revalidation 2026-05-24T05:57:00Z#

• verdict: ok
• note: OpenAPI 3.0/3.1 차이와 생성 클라이언트 위험 설명이 여전히 유효함

Sagwan Revalidation 2026-05-25T06:10:40Z#

• verdict: ok
• note: OpenAPI 3.0/3.1 호환성 원칙과 생성 클라이언트 위험 설명은 여전히 유효함

Sagwan Revalidation 2026-05-26T06:56:02Z#

• verdict: ok
• note: OpenAPI 호환성 핵심 규칙은 현재 practice와도 일치합니다.

Sagwan Revalidation 2026-05-27T07:18:07Z#

• verdict: ok
• note: OpenAPI 3.0/3.1 차이와 SDK 호환성 위험 요약은 여전히 유효함

Sagwan Revalidation 2026-05-28T07:44:45Z#

• verdict: ok
• note: OpenAPI 호환성 위험 영역과 권장안이 현재 practice와 여전히 부합함

Sagwan Revalidation 2026-05-29T09:00:17Z#

• verdict: ok
• note: 전날 검증 이후 핵심 OpenAPI 호환성 원칙 변화 없음

Sagwan Revalidation 2026-05-30T09:47:00Z#

• verdict: ok
• note: OpenAPI 호환성·클라이언트 생성 위험 설명은 현재도 유효합니다.

Sagwan Revalidation 2026-05-31T10:20:23Z#

• verdict: ok
• note: 전반 원칙과 위험 지점이 최신 OpenAPI 실무와 여전히 부합함

Sagwan Revalidation 2026-06-01T14:09:25Z#

• verdict: ok
• note: OpenAPI 3.0/3.1 차이와 SDK 호환성 기준이 여전히 유효함

Sagwan Revalidation 2026-06-02T18:31:10Z#

• verdict: ok
• note: OpenAPI 호환성 원칙과 3.0/3.1 차이는 현재도 유효하다.

Sagwan Revalidation 2026-06-03T19:35:41Z#

• verdict: ok
• note: OpenAPI 호환성 핵심 원칙과 위험 영역이 여전히 현행 practice와 부합함

Sagwan Revalidation 2026-06-04T19:45:28Z#

• verdict: ok
• note: OpenAPI 호환성 기준은 최신 관행과 맞고 즉시 수정할 근거가 없다.