llm-wiki/raw/official-docs/openapi-spec-3-1-0.md

---
title: OpenAPI Specification v3.1.0 (OAS 3.1)
source_type: official-doc
url: https://spec.openapis.org/oas/v3.1.0
archive_url:
status: raw
confidence: high
tags: [openapi, api-spec, json-schema, contract-testing, deprecation, api-contract, openapi-initiative]
related_projects: []
related_branches: [feature-api-contract-baseline, feature-contract-verification-test-suite, feature-api-compatibility-deprecation-contract]
created: 2026-05-27
last_reviewed: 2026-05-27
---

# OpenAPI Specification v3.1.0 (OAS 3.1)

> Layer: `raw/official-docs/` — OpenAPI Initiative (OAI) 의 OpenAPI Specification v3.1.0 발췌. JSON Schema 2020-12 와의 full alignment 가 OAS 3.0 대비 가장 큰 변경. RESTful API 의 machine-readable contract 정의의 1차 표준.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-api-contract-baseline]] | D10 — API contract 의 source-of-truth 를 OpenAPI 3.1 schema 로 정하고, JSON Schema 2020-12 dialect 의 정확한 의미론 정의 |
| [[raw/branch-notes/feature-contract-verification-test-suite]] | OpenAPI schema 를 입력으로 한 contract test (Schemathesis / Dredd / Pact) 의 표준 reference |
| [[raw/branch-notes/feature-api-compatibility-deprecation-contract]] | Operation Object 의 `deprecated: true` 필드 + Schema Object 의 deprecation 표현 표준 근거 |

## 컨텍스트

ca-tmpl 의 API contract baseline 결정 시 "spec source-of-truth 를 무엇으로 둘 것인가" (springdoc-generated OpenAPI vs hand-written YAML vs code-first annotation) 의 표준 근거. OAS 3.1 의 JSON Schema 2020-12 alignment 가 ca-tmpl 의 schema validation (Jakarta Validation `@Valid`) 과 OpenAPI schema 의 align 가능성을 결정. Contract verification 도구 (Schemathesis, Dredd) 는 모두 OpenAPI 를 입력으로 받음.

## 출처 / Source

- 원본 URL: https://spec.openapis.org/oas/v3.1.0
- 아카이브 URL: (미수집)
- 발행 조직: OpenAPI Initiative (OAI) — Linux Foundation 산하
- 발행일: 2021-02-15 (OAS v3.1.0) — 이후 patch: 3.1.1 (2024-10)
- 관련: JSON Schema Specification Draft 2020-12, BCP 14 (RFC 2119 + RFC 8174 — normative keywords), RFC 6901 (JSON Pointer)
- 마지막 확인일: 2026-05-27 (WebFetch via https://spec.openapis.org/oas/v3.1.0)

## 왜 저장했는지 / Why archived

ca-tmpl 의 API contract baseline (D10) 결정 — "OpenAPI 3.1 + JSON Schema 2020-12 dialect" 를 spec SSOT 로 채택할 때 따라야 할 normative reference. Contract verification 도구의 입력 형식 + deprecation marker (`deprecated: true`) 의 표준 정의 근거. company tech blog (Stripe / Square 등) 의 OpenAPI 사례를 "official best practice" 로 부르려면 본 OAI spec 이 corroborate 해야 함.

## 핵심 인용 / Key quotes (verbatim, 2026-05-27 WebFetch)

> [§2 Introduction — Normative Language] "The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14."

> [§2 Introduction — OpenAPI Definition] "The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service."

> [§4.3 Document Structure] "An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author."

> [§4.4 Data Types] "Data types in the OAS are based on the types supported by the JSON Schema Specification Draft 2020-12."

> [§4.8.7 Components Object] "Holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced."

> [§4.8.10 Operation Object — Parameters] "A list of parameters that are applicable for this operation. If a parameter is already defined at the Path Item, the new definition will override it but can never remove it."

> [§4.8.24 Schema Object] "Models are defined using the Schema Object, which is a superset of JSON Schema Specification Draft 2020-12."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| OPENAPI31-C1 | OAS 3.1 의 MUST / MUST NOT / SHOULD 등 normative keyword 는 BCP 14 (RFC 2119 + RFC 8174) 의 정의에 따라 해석 | [§2 Introduction] "The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14." | `official-standard` | OAS 3.1 spec 의 normative requirement 해석 | spec 본문의 어느 부분이 normative vs informative 인지의 정확한 분류는 본 인용 범위 밖 |
| OPENAPI31-C2 | OAS 는 HTTP API 에 대한 standard, language-agnostic interface 를 정의 — human + machine 양쪽이 서비스 capability 를 discover/understand | [§2 Introduction] "The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service." | `official-standard` | OAS 의 scope (HTTP API 만, gRPC/GraphQL/AsyncAPI 미포함) + 목적 (machine-readable contract) | OAS 가 implementation 을 generate 한다는 뜻은 아님 — discover/understand 까지. code generation 은 도구 (openapi-generator 등) 의 책임 |
| OPENAPI31-C3 | OpenAPI document 는 single document 이거나 multiple connected parts 로 분할 가능 (작성자 재량 — MAY) | [§4.3 Document Structure] "An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author." | `official-standard` | OAS document 의 file 구조 — monolithic vs split (e.g., `$ref` 통한 외부 파일) | split 의 정확한 mechanism (`$ref` syntax, file resolution) 은 본 인용 범위 밖 — §4.3 의 더 상세한 부분 별도 |
| OPENAPI31-C4 | OAS 의 Data Type 은 JSON Schema Specification Draft 2020-12 가 지원하는 type 에 base | [§4.4 Data Types] "Data types in the OAS are based on the types supported by the JSON Schema Specification Draft 2020-12." | `official-standard` | OAS 3.1 schema 의 type 어휘 (`string`, `integer`, `number`, `boolean`, `array`, `object`, `null`) + validation keyword (`minLength`, `pattern`, `enum` 등) | JSON Schema 2020-12 의 모든 keyword 가 OAS 에서 동작하는 것은 아님 — OAS 3.1 가 일부 keyword 의 의미를 재정의/제한 (별도 §4.8.24 참조) |
| OPENAPI31-C5 | Components Object 는 reusable object 의 집합. **components 내 정의 자체는 API 에 effect 없음** — 명시적으로 `$ref` 로 참조되어야 효과 발생 | [§4.8.7 Components Object] "Holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced." | `official-standard` | OAS 의 schema reusability 모델 (DTO 정의를 components/schemas 에 두고 `$ref` 로 참조) | components 에 정의된 unused schema 가 자동으로 cleanup 된다는 뜻은 아님 — 도구 (openapi-generator) 의 책임 |
| OPENAPI31-C6 | Operation Object 의 parameter 정의는 Path Item 의 parameter 를 override 가능하나 **remove 는 불가** | [§4.8.10 Operation Object] "A list of parameters that are applicable for this operation. If a parameter is already defined at the Path Item, the new definition will override it but can never remove it." | `official-standard` | Path Item + Operation 의 parameter inheritance 모델 — common parameter 의 path-level 정의 + operation-level override | Path Item parameter 가 모든 child operation 에 항상 적용된다는 뜻 — operation 이 명시적으로 omit 할 수 없음 |
| OPENAPI31-C7 | Schema Object 는 JSON Schema Specification Draft 2020-12 의 **superset** | [§4.8.24 Schema Object] "Models are defined using the Schema Object, which is a superset of JSON Schema Specification Draft 2020-12." | `official-standard` | OAS Schema Object 의 vocabulary 범위 — JSON Schema 2020-12 + OAS-specific extensions (e.g., `discriminator`, `xml`, `example`, `deprecated`) | OAS Schema 가 JSON Schema 의 모든 keyword 를 동일 의미로 지원한다는 뜻은 아님 — 일부 OAS-specific keyword 추가됨. 또한 OAS 3.0 (Draft 2020-12 와 호환 안됨) 과의 마이그레이션 호환성은 본 인용 범위 밖 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `OPENAPI31-C1`~`C2`: OAS 의 normative keyword 의미 + scope/목적
  - `OPENAPI31-C3`~`C4`: document 구조 (split MAY) + JSON Schema 2020-12 type base
  - `OPENAPI31-C5`~`C6`: components reusability 모델 + parameter inheritance
  - `OPENAPI31-C7`: Schema Object 가 JSON Schema 2020-12 의 superset
- **이 자료가 증명하지 않는 것**:
  - `deprecated: true` 의 정확한 의미론 — 본 발췌에 직접 인용 없음 (§4.8.10 Operation Object 의 `deprecated` boolean 필드는 spec 본문에 정의되어 있으나 본 raw 에 인용 없음 — 별도 발췌 필요)
  - Operation Object 의 `summary`, `description`, `responses`, `requestBody` 등 다른 필드의 정의 — 본 raw 는 parameter inheritance 만
  - `$ref` 의 resolution rule — RFC 6901 (JSON Pointer) 와의 정확한 alignment
  - OAS 3.0 → 3.1 migration 시 breaking change 목록 (`nullable` deprecated → `type: [...,null]` 등)
  - springdoc-openapi 가 Spring annotation (`@RequestMapping` 등) 을 OAS 3.1 spec 으로 정확히 generate 하는지 (springdoc vendor 책임)
  - Schemathesis / Dredd / Pact 의 OAS 3.1 호환성 — 각 도구 vendor doc 별도
  - JSON Schema 2020-12 의 모든 keyword 카탈로그 (`if`/`then`/`else`, `unevaluatedProperties` 등) — JSON Schema spec 별도
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - ca-tmpl 의 springdoc-openapi 버전이 OAS 3.1 (vs 3.0) 을 generate 하는지 (springdoc 2.x 이후 OAS 3.1 default)
  - Jakarta Validation 의 `@Valid` / `@NotNull` 등이 OAS 3.1 schema 의 어떤 keyword 로 mapping 되는지
  - contract verification 도구 (Schemathesis 등) 가 OAS 3.1 의 JSON Schema 2020-12 keyword (`prefixItems`, `unevaluatedProperties`) 를 모두 지원하는지
  - Operation Object 의 `deprecated: true` 가 ca-tmpl 의 API deprecation policy (Sunset header, deprecation date 등) 와 어떻게 연계되는지 — 별도 발췌 + 정책 결정

## 메모 / Notes

- WebFetch 가 본 spec 의 핵심 7 quote 를 verbatim 반환. spec 본문이 매우 길어 (수백 페이지) §4.8.24 Schema Object 의 모든 keyword (특히 `discriminator`, `xml`, `example`, `externalDocs`) 발췌는 별도 raw 필요.
- §4.8.10 Operation Object 의 `deprecated: boolean` 필드 정의 — 본 발췌에 미포함. `feature-api-compatibility-deprecation-contract` 의 D11/D12 결정 시 별도 발췌 필수.
- OAS 3.1 vs 3.0 의 핵심 차이: (1) JSON Schema Draft 2020-12 alignment (3.0 은 Wright Draft 00 변형), (2) `nullable` deprecated, (3) webhooks 추가, (4) `info.summary` 추가, (5) `license.identifier` (SPDX) 추가. 본 raw 는 alignment (C4/C7) 만 직접 인용.
- ca-tmpl 의 RESTful controller 가 springdoc-openapi 로 생성된 OAS 3.1 spec 과 hand-written YAML 중 어느 것을 SSOT 로 둘지는 별도 결정 — 본 표준은 둘 다 허용.

## Related / 관련

- 같은 주제 다른 official-doc:
  - JSON Schema Specification Draft 2020-12 (https://json-schema.org/draft/2020-12/json-schema-core) — 별도 raw 작성 후보
  - RFC 7807 / `application/problem+json` — error response schema 에 사용 시 [[raw/official-docs/problem-detail-rfc-7807]] 참조
  - RFC 9110 — OAS response 의 status code 의미 [[raw/official-docs/rfc9110-http-semantics]] 참조
- 인용하는 branch:
  - [[raw/branch-notes/feature-api-contract-baseline]] (D10)
  - [[raw/branch-notes/feature-contract-verification-test-suite]]
  - [[raw/branch-notes/feature-api-compatibility-deprecation-contract]]
- 인용하는 project:
  - [[raw/project-notes/ca-skeleton-operational-contract]]
- 인용한 wiki 요약: (미작성)