OpenAPI 명세서 v3.2.0

OAD의 각 문서는 반드시(MUST) 참조 대상 탐지를 위해 완전히 파싱되어야 합니다. 이는 JSON Schema Specification Draft 2020-12의 파싱 요구사항을 포함하며, URI의 상대 참조에 관한 기본 URI에 대한 적절한 수정 사항을 적용해야 합니다. 참조 대상은 OpenAPI Object의 $self 필드, Schema Object의 $id, $anchor, $dynamicAnchor 키워드를 포함한 필드들로 정의됩니다.

구현체는 OAD의 가능한 일부로 제공된 모든 문서를 완전히 파싱하기 전에는 참조를 미해결 상태로 간주해서는 안 됩니다(MUST NOT).

참조를 해결할 때 문서의 해당 부분만 파싱하면 구현-정의 또는 정의되지 않은 동작이 나타날 수 있으며, 자세한 설명은 부분적 파싱에 대한 경고 및 부록 G를 참고하세요.

OpenAPI 설명 내에서 사용되는 참조 URI나 외부 문서, 라이선스와 같은 보조 정보 대상 URI들은 식별자로 해결되며, 본 명세에서는 URI로 설명됩니다(API URL과는 다릅니다). 일부 URI 필드는 역사적으로 url이라는 이름을 가졌지만, 설명 텍스트에는 올바른 "URI" 용어가 사용됩니다.

문서 파싱에서 언급했듯, 여러 필드들로 OpenAPI 문서 또는 Schema Object와 URI가 연결될 수 있으며, 이는 문서나 스키마의 실제 위치와 일치하지 않을 수 있습니다. 이렇게 하면 로컬 파일시스템, 제한된 네트워크 등 다양한 배포 환경에서 동일한 참조를 사용할 수 있게 됩니다.

달리 명시되지 않은 한, URI 필드는 모두 [RFC3986] Section 4.2에서 정의한 대로 상대 참조가 가능해야 합니다(MAY).

이 명세의 여러 기능은 URI를 기반으로 하지 않는 연결을 OAD 내의 다른 부분에 대해 해결해야 합니다.

단일 문서 OAD에서는 이러한 연결이 명확하게 해결되지만, 다중 문서 OAD에서의 해결 과정은 본 섹션에 설명된 제약 내에서 구현-정의입니다. 경우에 따라, URI 기반 대안이 명확하게 제공될 수 있으며, 상호 운용성을 최대화하려면 이 대안을 사용하는 것이 권장됩니다(RECOMMENDED).

참조(비엔트리) 문서에서 Components Object 및 Tag Object 이름을 해결할 때, 툴이 현재 문서가 아니라 엔트리 문서에서 해결하도록 하는 것이 권장됩니다(RECOMMENDED). Operation Object를 operationId로 기반해 해결하려면 모든 문서에서 파싱된 Operation Object를 고려해야 합니다(RECOMMENDED).

암시적 연결 해석에서는 URI 해석 방식이나 타겟 범위가 절대적으로 변경되지 않습니다.

상세 내용 및 암시적 연결을 사용하는 객체와 필드 목록은 부록 G: 파싱 및 해석 가이드를 참조하세요.

다음 OpenAPI 문서의 검색 URI가 https://device1.example.com라고 가정합니다:

openapi: 3.2.0
$self: https://apidescriptions.example.com/foo
info:
  title: Example API
  version: 1.0
servers:
- url: .
  description: The production API on this device
- url: ./test
  description: The test API on this device

API URL의 경우 OpenAPI 문서를 식별하는 $self 필드는 무시되고 대신 검색 URI가 사용됩니다. 이로 인해 정규화된 프로덕션 URL은 https://device1.example.com이 되고, 정규화된 테스트 URL은 https://device1.example.com/test이 됩니다.

다음 경로들을 가정하면, 구체적 정의인 /pets/mine가 사용될 경우 먼저 매칭됩니다:

  /pets/{petId}
  /pets/mine

다음 경로들은 동일하다고 간주되어 무효입니다:

  /pets/{petId}
  /pets/{name}

다음과 같은 경우 모호한 해석이 발생할 수 있습니다:

  /{entity}/me
  /books/{id}

이들 필드는 content 또는 schema와 함께 모두 사용할 수 있습니다(MAY).

example와 examples 필드는 상호 배타적입니다; 검증 요구사항에 대한 지침은 Working with Examples를 참조하세요.

이 객체는 MAY Specification Extensions로 확장될 수 있습니다.

참고: "Cookie"를 name으로 사용하면서 in이 "header"인 것은 금지되지 않지만, 그렇게 정의된 쿠키 파라미터의 효과는 정의되지 않습니다; 대신 in: "cookie"를 사용하세요.

단순한 시나리오의 경우, schema와 style로 파라미터의 구조와 문법을 설명할 수 있습니다.

이 필드들은 in: "querystring"와 함께 사용해서는 안 됩니다(MUST NOT).

in: "header" 또는 in: "cookie", style: "cookie"인 schema가 있는 파라미터의 경우 주의가 필요합니다:

• 이 값들을 직렬화할 때 URI 퍼센트 인코딩을 적용해서는 안 됩니다(MUST NOT).
• 이 파라미터를 파싱할 때 보이는 퍼센트 인코딩을 디코드해서는 안 됩니다(MUST NOT).
• 자동으로 인코딩/디코딩 단계를 수행하는 RFC6570 구현을 사용하는 경우, 사용 전 그 단계를 되돌려야 합니다(MUST).

이런 경우 구현체는 값을 변경하거나 인용/이스케이프하려고 시도하기보다는 있는 그대로 전달해야 합니다(MUST), 헤더의 인용 규칙과 쿠키의 이스케이프 관례가 매우 다양하기 때문입니다. 인용 및 이스케이프에 대한 안내는 부록 D를 참조하세요.

추가 지침은 부록 C: RFC6570 기반 직렬화 사용을 참조하세요.

보다 복잡한 시나리오에서는 content 필드가 파라미터의 미디어 타입과 스키마를 정의하고 사용 예시를 제공할 수 있습니다.

in: "querystring" 및 application/x-www-form-urlencoded와 함께 사용할 때는 Encoding the x-www-form-urlencoded Media Type를 참조하세요.

OpenAPI Initiative는 이 명세에서 기대되는 미디어 타입 지원을 요약하고 각 미디어 타입과 연관된 섹션을 색인화하는 Media Type Registry를 운영합니다. 또한 IANA 등록(존재하는 경우) 및 각 미디어 타입과 관련된 주요 명세 문서들을 연결합니다. 이 레지스트리에 추가된 미디어 타입(확장 또는 이후 버전의 OpenAPI 명세에 추가된 것)은 이 버전의 OAS 구현체에서 MAY 지원될 수 있습니다.

본 명세에서 연속적 미디어 타입(sequential media type)은 헤더, 푸터, 엔벨로프 또는 시퀀스 외의 메타데이터 없이 반복 구조로만 구성되는 모든 미디어 타입으로 정의됩니다.

다음은 연속적 미디어 타입의 예시들입니다(일부는 IANA에 등록되지 않았지만 일반적으로 사용됨):

  application/jsonl
  application/x-ndjson
  application/json-seq
  application/geo+json-seq
  text/event-stream
  multipart/mixed

위의 처음 세 가지에서는 반복 구조가 어떤 JSON 값이 됩니다. 네 번째는 application/geo+json 구조화 값을 반복하고, text/event-stream은 Server-Sent Events와 관련된 커스텀 텍스트 포맷을 반복합니다. 마지막으로 multipart/mixed는 모든 미디어 타입의 문서들을 순서대로 나열하며 때로 스트리밍됩니다. multipart 형식은 기술적으로 서문(preamble)과 후문(epilogue)을 허용하지만 RFC는 이를 무시하도록 지시하므로 본 명세는 이를 모델링하지 않습니다.

구현체는 연속적 미디어 타입을 JSON Schema 데이터 모델로 매핑할 때 값들을 동일한 순서의 배열로 간주하여 매핑을 지원해야 합니다(MUST).

스트리밍 컨텍스트에서 연속적 미디어 타입을 처리하는 방법에 대한 자세한 내용(특히 text/event-stream에 대한 특별 고려사항)은 Complete vs Streaming Content를 참고하세요. multipart 타입의 경우 Encoding By Position도 참고하세요.

maxLength 키워드는 문자열 데이터(인코딩된 바이너리 데이터 포함) 또는 비인코딩 바이너리 데이터로 구성된 스트리밍 페이로드의 예상 상한 길이를 설정하는 데 MAY 사용될 수 있습니다. 비인코딩 바이너리 데이터의 경우 길이는 옥텟 수입니다. 이 사용 사례에서 maxLength는 JSON Schema가 바이너리 데이터에 직접 적용되지 않기 때문에 정규 JSON Schema 평가 외부에서 구현될 수 있습니다. 인코딩된 바이너리 스트림을 전체 메모리에 저장하는 것은 비현실적일 수 있습니다.

encoding 필드의 동작은 웹 폼을 지원하도록 설계되었으므로, 반복 값을 허용하는 이름-값 쌍으로 구조화된 미디어 타입에 대해서만 정의됩니다. 특히 application/x-www-form-urlencoded와 multipart/form-data가 해당됩니다.

encoding 필드를 사용하려면 해당 필드 아래의 각 키가 속성으로 반드시 존재해야 합니다(MUST); 해당 속성이 없는 encoding 항목은 무시되어야 합니다(SHALL). 배열 속성은 권장대로 각 배열 항목마다 동일한 name을 사용하여 하나의 인코딩된 값을 생성하도록 주어진 Encoding Object를 적용하여 처리해야 합니다([RFC7578] 참조). 최상위 비배열 속성 및 값, 그리고 최상위 배열 내의 배열 값 등 다른 모든 값 유형에 대해서는 Encoding Object가 값 전체에 적용되어야 합니다. 대상 미디어 타입에서의 이름-값 쌍 순서는 구현-정의입니다.

application/x-www-form-urlencoded의 경우, 인코딩 키는 파라미터 이름에 매핑되어야 하며 값은 Encoding Object 규칙에 따라 생성됩니다. Encoding the x-www-form-urlencoded Media Type에서 예시와 안내를 확인하세요.

multipart의 경우 인코딩 키는 각 파트의 Content-Disposition: form-data 헤더의 name parameter에 매핑되어야 합니다. 비-ASCII 파트 이름에 대한 지침은 [RFC7578]를 참조하세요.

encoding 필드가 있는 경우와 없는 경우 모두에 대한 추가 안내 및 예시는 Encoding multipart Media Types를 참조하세요.

대부분의 multipart 미디어 타입(모든 multipart 타입의 구문 분석 규칙을 정의하는 multipart/mixed 포함)은 명명된 파트를 가지지 않습니다. 이러한 미디어 타입의 데이터는 한 파트당 하나의 항목을 가지는 배열로 모델링됩니다(순서 중요).

prefixEncoding 및/또는 itemEncoding 필드를 사용하려면 itemSchema 또는 배열 형태의 schema가 있어야 합니다(MUST). 이들 필드는 JSON Schema의 prefixItems 및 items 키워드와 유사하며, prefixEncoding은 데이터 배열에서 동일한 위치의 값에 각각 적용되는 Encoding Objects 배열을 제공하고, itemEncoding은 배열의 나머지 항목 전체에 단일 Encoding Object를 적용합니다. 인스턴스 배열이 prefixEncoding 배열보다 짧아도 오류가 아니며, 추가 Encoding Objects는 무시되어야 합니다(SHALL).

itemEncoding 필드는 스트리밍 multipart 콘텐츠 지원을 위해 itemSchema와 함께 사용할 수도 있습니다.

prefixEncoding 필드는 고정된 파트 순서를 요구하기 위해 어떤 multipart 콘텐츠와도 함께 사용할 수 있습니다. 이에는 Encoding Object의 headers 필드를 사용해 Content-Disposition 및 파트 이름을 제공해야 하는 multipart/form-data가 포함됩니다(속성 이름이 자동으로 제공되지 않기 때문입니다).

이전 버전의 명세는 multipart 미디어 타입(특히 multipart/form-data 외의 경우)에 대해 각 파트의 Content-Disposition: form-data 헤더의 name parameter를 사용하도록 권고하여 encoding 필드의 한계를 우회하도록 제안했습니다. 구현체는 이 워크어라운드를 선택적으로 지원할 수 있지만, 이 사용 방식은 일반적이지 않으므로 비-form-data multipart 미디어 타입 구현체는 이를 지원할 가능성이 낮습니다.

이 예시는 YAML로 작성되었기 때문에 Example Object의 value 필드는 JSON으로 간단히 변환 가능한 YAML 형식으로 작성할 수 있습니다. 이는 JSON을 문자열로 임베드할 필요를 피합니다.

application/json:
  schema:
    $ref: '#/components/schemas/Pet'
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: An example of a dog with a cat's name
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: '#/components/examples/frog-example'

대안으로, 모든 JSON이 유효한 YAML이므로 예시 값은 YAML 문서 내에서 JSON 문법을 그대로 사용할 수 있습니다:

application/json:
  schema:
    $ref: '#/components/schemas/Pet'
  examples:
    cat:
      summary: An example of a cat
      value: {
        "name": "Fluffy",
        "petType": "Cat",
        "color": "White",
        "gender": "male",
        "breed": "Persian"
      }
    dog:
      summary: An example of a dog with a cat's name
      value: {
        "name": "Puma",
        "petType": "Dog",
        "color": "Black",
        "gender": "Female",
        "breed": "Mixed"
      }
    frog:
      $ref: '#/components/examples/frog-example'

시퀀스의 항목이 JSON 값인 모든 연속적 미디어 타입에 대해서는 각 값의 변환이 필요하지 않습니다. JSON Text Sequences(예: application/json-seq)와 RFC 참조의 +json-seq 접미사, JSON Lines(application/jsonl), NDJSON(application/x-ndjson) 등이 이 범주에 포함됩니다. JSON Lines와 NDJSON의 미디어 타입은 IANA에 등록되지 않았지만 일반적으로 사용됩니다.

다음 예시는 스트리밍 로그 항목과 쿼리에 대한 고정 길이 집합 반환을 위한 Media Type Objects를 보여주며, schema와 itemSchema의 관계와 각각을 언제 사용해야 하는지를 설명합니다.

components:
  schemas:
    LogEntry:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        level:
          type: integer
          minimum: 0
        message:
          type: string
    Log:
      type: array
      items:
        $ref: "#/components/schemas/LogEntry"
      maxItems: 100
  examples:
    LogJSONSeq:
      summary: Log entries in application/json-seq
      # JSON Text Sequences require an unprintable character
      # that cannot be escaped in a YAML string, and therefore
      # must be placed in an external document shown below
      externalValue: examples/log.json-seq
    LogJSONPerLine:
      summary: Log entries in application/jsonl or application/x-ndjson
      description: JSONL and NDJSON are identical for this example
      # Note that the value must be written as a string with newlines,
      # as JSONL and NDJSON are not valid YAML
      value: |
        {"timestamp": "1985-04-12T23:20:50.52Z", "level": 1, "message": "Hi!"}
        {"timestamp": "1985-04-12T23:20:51.37Z", "level": 1, "message": "Bye!"}
  responses:
    LogStream:
      description: |
        A stream of JSON-format log messages that can be read
        for as long as the application is running, and is available
        in any of the sequential JSON media types.
      content:
        application/json-seq:
          itemSchema:
            $ref: "#/components/schemas/LogEntry"
          examples:
            JSON-SEQ:
              $ref: "#/components/examples/LogJSONSeq"
        application/jsonl:
          itemSchema:
            $ref: "#/components/schemas/LogEntry"
          examples:
            JSONL:
              $ref: "#/components/examples/LogJSONPerLine"
        application/x-ndjson:
          itemSchema:
            $ref: "#/components/schemas/LogEntry"
          examples:
            NDJSON:
              $ref: "#/components/examples/LogJSONPerLine"
    LogExcerpt:
      description: |
        A response consisting of no more than 100 log records,
        generally as a result of a query of the historical log,
        available in any of the sequential JSON media types.
      content:
        application/json-seq:
          schema:
            $ref: "#/components/schemas/Log"
          examples:
            JSON-SEQ:
              $ref: "#/components/examples/LogJSONSeq"
        application/jsonl:
          schema:
            $ref: "#/components/schemas/Log"
          examples:
            JSONL:
              $ref: "#/components/examples/LogJSONPerLine"
        application/x-ndjson:
          schema:
            $ref: "#/components/schemas/Log"
          examples:
            NDJSON:
              $ref: "#/components/examples/LogJSONPerLine"

우리의 application/json-seq 예시는 개행 문자와 인쇄 불가능한 레코드 구분자(0x1E)를 사용하기 때문에 외부 문서로 두어야 합니다; YAML 블록 리터럴에서 이를 이스케이프할 수 없습니다:

0x1E{
  "timestamp": "1985-04-12T23:20:50.52Z",
  "level": 1,
  "message": "Hi!"
}
0x1E{
  "timestamp": "1985-04-12T23:20:51.37Z",
  "level": 1,
  "message": "Bye!"
}

이 예시에서는 Special Considerations for Server-Sent Events 섹션에 제공된 일반 이벤트 스키마가 #/components/schemas/Event에 있다고 가정합니다:

description: A request body to add a stream of typed data.
required: true
content:
  text/event-stream:
    itemSchema:
      $ref: "#/components/schemas/Event"
      required: [event]
      oneOf:
      - properties:
          event:
            const: addString
      - properties:
          event:
            const: addInt64
          data:
            $comment: |
              Since the `data` field is a string,
              we need a format to signal that it
              should be handled as a 64-bit integer.
            format: int64
      - properties:
          event:
            const: addJson
          data:
            $comment: |
              These content fields indicate
              that the string value should
              be parsed and validated as a
              JSON document (since JSON is not
              a binary format, `contentEncoding`
              is not needed)
            contentMediaType: application/json
            contentSchema:
              type: object
              required: [foo]
              properties:
                foo:
                  type: integer

다음 text/event-stream 문서는 위 예시의 유효한 요청 본문의 예입니다:

event: addString
data: This data is formatted
data: across two lines
retry: 5

event: addInt64
data: 1234.5678
unknownField: this is ignored

: This is a comment
event: addJSON
data: {"foo": 42}

이 스트림이 어떻게 처리되는지 더 명확히 보기 위해, 다음은 동등한 JSON Lines 문서로서 숫자 및 JSON 데이터가 문자열로 처리되는 방식과 알려지지 않은 필드 및 주석이 무시되어 스키마 검증에 전달되지 않는 방식을 보여줍니다:

{"event": "addString", "data": "This data is formatted\nacross two lines", "retry": 5}
{"event": "addInt64", "data": "1234.5678"}
{"event": "addJSON", "data": "{\"foo\": 42}"}

이들 필드는 아래 섹션에 정의된 RFC6570 스타일 직렬화 필드의 사용 여부와 상관없이 사용할 수 있습니다(MAY).

이 객체는 MAY Specification Extensions로 확장될 수 있습니다.

contentType의 기본값은 다음과 같습니다. contentEncoding 열의 n/a는 contentEncoding의 존재 또는 값이 무관함을 의미합니다. 이 표는 Encoding Object가 적용되는 값의 유형에 기반합니다(Encoding Usage and Restrictions 참조). Encoding By Name의 경우, 이 값은 "array" 타입의 속성에 대해 배열 항목에 해당하고, 다른 모든 타입에서는 전체 값에 해당합니다. 따라서 표의 array 행은 이름으로 인코딩할 때 최상위 배열 내부의 배열 값 항목에만 적용됩니다.

null 타입을 처리하는 방식은 null 값이 어떻게 직렬화되는지에 따라 달라집니다. null 값이 완전히 생략된다면 contentType는 무의미합니다. 데이터 타입 변환 옵션에 대한 논의는 Appendix B를 참조하세요.

multipart/form-data에 대해 RFC6570 스타일 직렬화를 사용할 때는 URI 퍼센트 인코딩을 적용해서는 안 되며(MUST NOT), allowReserved의 값은 영향을 미치지 않습니다. 추가 안내는 Appendix C: Using RFC6570 Implementations를 참조하세요.

style, explode, 또는 allowReserved 중 적어도 하나가 명시적으로 존재하는 것은 schema와 in: "query" Parameter Objects를 사용하는 것과 동등합니다. 이들 세 필드가 모두 없는 경우는 content를 사용하는 것과 동등하지만, 미디어 타입은 Media Type Object를 통해서가 아니라 contentType에 의해 지정된다는 점이 다릅니다.

encoding 필드가 없을 때 직렬화 전략은 Encoding Object의 기본값에 기반합니다:

requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            type: object
            properties: {}

이 예에서 id가 f81d4fae-7dec-11d0-a765-00a0c91e6bf6이고 ZIP+4를 포함한 미국식 주소가 다음과 같다고 가정하면:

{
  "streetAddress": "123 Example Dr.",
  "city": "Somewhere",
  "state": "CA",
  "zip": "99999+1234"
}

JSON 값의 가장 간결한 표현(불필요한 공백 제거)을 가정하면, 요청 본문은 다음과 같을 것이며 공백 문자는 +로, 그리고 +, ", :, ,, {, } 등은 각각 %2B, %22, %3A, %2C, %7B, %7D로 퍼센트-인코딩됩니다:

id=f81d4fae-7dec-11d0-a765-00a0c91e6bf6&address=%7B%22streetAddress%22%3A%22123+Example+Dr.%22%2C%22city%22%3A%22Somewhere%22%2C%22state%22%3A%22CA%22%2C%22zip%22%3A%2299999%2B1234%22%7D

Encoding Object의 기본 동작에 따라 id 키워드는 text/plain로 취급되어 있는 그대로 직렬화됩니다. 만약 application/json으로 취급되면 직렬화된 값은 따옴표를 포함한 JSON 문자열이 되며 따옴표는 %22로 퍼센트-인코딩됩니다.

다음은 id 파라미터가 text/plain 대신 application/json으로 직렬화된 후 WHATWG-URL의 form-urlencoded 규칙에 따라 인코딩된 예시입니다:

id=%22f81d4fae-7dec-11d0-a765-00a0c91e6bf6%22

application/x-www-form-urlencoded은 텍스트 형식이므로 바이너리 데이터는 base64로 인코딩해야 합니다.

requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          name:
            type: string
          icon:
            # The default content type with `contentEncoding` present
            # is `application/octet-stream`, so we need to set the correct
            # image media type(s) in the Encoding Object.
            type: string
            contentEncoding: base64url
  encoding:
    icon:
      contentType: image/png, image/jpeg

예: name이 example이고 icon이 빨간색 2x2 PNG라면 요청 본문은 다음과 같습니다:

name=example&icon=iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAABGdBTUEAALGPC_xhBQAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAAqADAAQAAAABAAAAAgAAAADO0J6QAAAAEElEQVQIHWP8zwACTGCSAQANHQEDqtPptQAAAABJRU5ErkJggg%3D%3D

= 패딩 문자는 contentEncoding: base64url 같은 "URL safe" 인코딩을 사용하더라도 퍼센트-인코딩되어야 합니다. 일부 base64 디코더는 RFC4648 섹션에 따라 패딩 없이도 처리할 수 있지만 보장되지 않으므로 호환성을 위해 패딩을 유지하고 퍼센트-디코딩에 의존하는 것이 더 안전할 수 있습니다.

contentType에 여러 값이 지정된 경우에도 파트의 실제 Content-Type이 문서에 포함되므로 파싱은 간단합니다.

인코딩 및 직렬화 시 구현체는 애플리케이션이 의도한 미디어 타입을 표시할 수 있는 메커니즘을 반드시 제공해야 합니다(MUST). 구현체는 대안으로 미디어 타입 스니핑([SNIFF])을 제공할 수 있지만, 보안 위험 때문에 기본 동작으로 이것을 사용해서는 안 됩니다(MUST NOT).

멀티파트 필드에 대해 contentEncoding을 사용하는 것은 해당 값을 요구하는 스키마를 가진 Content-Transfer-Encoding 헤더를 포함하는 Encoding Object를 지정하는 것과 동등합니다. 만약 멀티파트 필드에 대해 contentEncoding이 사용되었고, 동시에 Encoding Object의 headers 필드에 Content-Transfer-Encoding가 있어 그 스키마가 contentEncoding의 값을 허용하지 않는다면 직렬화 및 파싱 결과는 정의되지 않습니다.

Working with Binary Data에서 언급된 바와 같이, Encoding Object의 contentType이 (명시적이든 암묵적이든) 스키마 객체의 contentMediaType과 불일치하는 경우 contentMediaType는 무시되어야 합니다(SHALL). 이 때문에 Encoding Object와 함께 contentMediaType를 사용하는 것은 권장되지 않습니다(NOT RECOMMENDED).

또한 Content-Transfer-Encoding은 HTTP에서 바이너리 데이터를 지원하는 multipart/form-data에 대해 더 이상 권장되지 않습니다([RFC7578] Section 4.7).

폼 미디어 타입의 퍼센트 인코딩 문제에 대한 상세 검토는 Appendix E를 참조하세요.

encoding 필드가 사용되지 않을 때 인코딩은 Encoding Object의 기본값에 의해 결정됩니다:

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          # default content type for a string without `contentEncoding`
          # is `text/plain`
          id:
            type: string
            format: uuid

          # default content type for a schema without `type`
          # is `application/octet-stream`
          profileImage: {}

          # for arrays, the `encoding` field applies the Encoding Object
          # to each item individually and determines the default content type
          # based on the type in the `items` subschema, which in this example
          # is an object, so the default content type for each item is
          # `application/json`
          addresses:
            type: array
            items:
              $ref: '#/components/schemas/Address'

encoding을 사용하면 바이너리 데이터에 대해 더 구체적인 타입을 설정하거나 복잡한 값에 대해 비-JSON 형식을 지정할 수 있습니다. 또한 각 파트에 대한 헤더도 설명할 수 있습니다:

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          # No Encoding Object, so use default `text/plain`
          id:
            type: string
            format: uuid

          # Encoding Object overrides the default `application/json` content type
          # for each item in the array with `application/xml; charset=utf-8`
          addresses:
            description: addresses in XML format
            type: array
            items:
              $ref: '#/components/schemas/Address'

          # Encoding Object accepts only PNG or JPEG, and also describes
          # a custom header for just this part in the multipart format
          profileImage: {}

      encoding:
        addresses:
          contentType: application/xml; charset=utf-8
        profileImage:
          contentType: image/png, image/jpeg
          headers:
            X-Rate-Limit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer

[RFC7578] Section 4.3에 따라, 단일 폼 필드에 대한 다중 파일 업로드는 각 파일 파트에 대해 동일한 이름(이 예에서는 file)을 사용하여 업로드합니다:

requestBody:
  content:
    multipart/form-data:
      schema:
        properties:
          # The property name `file` will be used for all files.
          file:
            type: array
            items: {}

앞서 Encoding Object의 contentType 필드 문서에서 본 바와 같이, items의 빈 스키마는 application/octet-stream 미디어 타입을 나타냅니다.

JSON 메타데이터 문서가 먼저 나오고 그 메타데이터가 설명하는 이미지를 뒤따르는 multipart/mixed 페이로드 예시:

multipart/mixed:
  schema:
    type: array
    prefixItems:
    - # default content type for objects
      # is `application/json`
      type: object
      properties:
        author:
          type: string
        created:
          type: string
          format: datetime
        copyright:
          type: string
        license:
          type: string
    - # default content type for a schema without `type`
      # is `application/octet-stream`, which we need
      # to override.
      {}
  prefixEncoding:
  - # Encoding Object defaults are correct for JSON
    {}
  - contentType: image/*

[RFC2557]에 설명된 바와 같이, 웹 페이지를 구성하는 리소스 집합은 multipart/related 페이로드로 전송될 수 있으며, 각 파트에 Content-Location 헤더를 정의하여 text/html 문서에서 보조 리소스로의 링크를 보존할 수 있습니다. 첫 번째 파트는 루트 리소스로 사용되므로(Content-ID 사용은 권장되지 않음) prefixItems와 prefixEncoding을 사용하여 첫 파트가 HTML 리소스여야 함을 정의하고, 그 뒤에는 여러 타입의 리소스를 임의의 순서로 허용합니다.

Content-Location 헤더는 그 값이 URI이므로 퍼센트 인코딩을 피하기 위해 content: {text/plain: {...}}를 사용하여 정의합니다. 자세한 내용은 Appendix D를 참조하세요.

components:
  headers:
    RFC2557NoContentId:
      description: Use Content-Location instead of Content-ID
      schema: false
    RFC2557ContentLocation:
      required: true
      content:
        text/plain:
          schema:
            $comment: Use a full URI (not a relative reference)
            type: string
            format: uri
  requestBodies:
    RFC2557:
      content:
        multipart/related; type=text/html:
          schema:
            prefixItems:
            - type: string
            items:
              anyOf:
              - type: string
              - $comment: To allow binary, this must always pass
          prefixEncoding:
          - contentType: text/html
            headers:
              Content-ID:
                $ref: '#/components/headers/RFC2557NoContentId'
              Content-Location:
                $ref: '#/components/headers/RFC2557ContentLocation'
          itemEncoding:
            contentType: text/css,text/javascript,image/*
            headers:
              Content-ID:
                $ref: '#/components/headers/RFC2557NoContentId'
              Content-Location:
                $ref: '#/components/headers/RFC2557ContentLocation'

이 예시는 대량의 사진을 캡처하여 호출자에게 스트리밍하는 장치를 가정합니다. 이전 예와 달리 여기서는 각 이미지를 도착했을 때(또는 소규모 배치로) 처리할 것으로 기대하므로 itemSchema를 사용합니다. 전체 스트림을 버퍼링하면 메모리가 부족해지기 때문입니다.

multipart/mixed:
  itemSchema:
    $comment: A single data image from the device
  itemEncoding:
    contentType: image/jpg

multipart/byteranges의 경우([RFC9110] Section 14.6), Content-Range 헤더가 필요합니다.

왜 content: {text/plain: {...}}를 사용하여 헤더 값을 설명하는지에 대한 설명은 Appendix D를 참조하세요.

multipart/byteranges:
  itemSchema:
    $comment: A single range of bytes from a video
  itemEncoding:
    contentType: video/mp4
    headers:
      Content-Range:
        required: true
        content:
          text/plain:
            schema:
              # The `pattern` regular expression that would
              # be included in practice is omitted for simplicity
              type: string

이는 첫 번째 파트가 JSON 배열이고 두 번째 파트가 중첩된 multipart/mixed 문서인 2-파트 multipart/mixed를 정의합니다. 중첩된 파트들은 XML, 일반 텍스트, PNG 이미지입니다.

multipart/mixed:
  schema:
    type: array
    prefixItems:
    - type: array
    - type: array
      prefixItems:
      - type: object
      - type: string
      - {}
  prefixEncoding:
    - {} # Accept the default application/json
    - contentType: multipart/mixed
      prefixEncoding:
      - contentType: application/xml
      - {} # Accept the default text/plain
      - contentType: image/png

value와 약식 example 필드는 serializedValue(또는 externalValue)와 동일한 의미론을 가지도록 의도되었지만, JSON(또는 JSON-호환 YAML) 표현과 최종 직렬화 형태 사이에 차이가 없을 때 더 편리한 문법을 허용합니다. application/json 또는 +json 미디어 타입에 대해 이 문법을 사용할 때, 이들 필드는 사실상 dataValue처럼 동작하므로 안전하게 사용할 수 있습니다.

데이터가 단일 문자열로 이루어지고 그 직렬화 대상이 text/plain처럼 문자열이 추가 이스케이프 없이 보장되어 직렬화되는 경우에도 이러한 필드는 안전하게 사용할 수 있습니다.

다른 직렬화 대상의 경우, “JSON 또는 YAML로 자연스럽게 표현될 수 있음”이라는 모호성 때문에 비호환성 문제가 발생할 수 있습니다. 실무에서는 비-JSON 대상에 대해 value와 약식 example의 동작이 구현체마다 달라질 수 있으므로 OAD 작성자는 상호운용성을 위해 다른 필드를 사용하는 것을 SHOULD 권장합니다.

이전 섹션의 주의사항을 염두에 두고, 약식 example이 단일 Example Object에 대해서는 value 대신 사용될 수 있다는 점을 고려하여 다음 지침을 따르세요.

스키마로 검증될 예시를 보여주려면:

• 검증 스키마와 예시를 함께 유지하려면 Schema Object의 examples 배열(JSON Schema draft 2020-12)을 사용하세요.
  • OAS v3.0과의 호환성이 필요하면 Schema Object의 단수형 example을 사용하세요.
• 예시를 직렬화된 형태의 예시와 연관시키거나 스키마와 별도로 유지하려면 Example Object의 dataValue 필드를 사용하세요.
  • OAS v3.1 또는 이전과의 호환성이 필요하고 값이 JSON이나 YAML로 자연스럽게 표현될 수 있다면 Example Object의 value 필드를 사용하세요.

HTTP/1.1 메시지를 구성하기 위해 실제 직렬화된 예시를 보여주려면:

• 직렬화가 유효한 유니코드 문자열로 표현될 수 있고 정확한 문자 인코딩을 보여줄 필요가 없다면 Example Object의 serializedValue를 사용하세요.
  • OAS v3.1 또는 이전과의 호환성이 필요한 경우에는 문자열 형태의 value를 사용하세요.
• 그 외의 값이나 예시를 문서 밖에서 별도로 유지하고자 할 경우 Example Object의 externalValue를 사용하세요.

serializedValue와 externalValue는 모두 직렬화된 형태를 반드시(MUST) 보여주어야 합니다. Media Type Objects의 경우 이는 적절한 미디어 타입의 문서이며, Encoding Object의 효과가 적용되어야 합니다. Parameter 및 Header Objects가 schema와 style를 사용하는 경우 직렬화 값의 정의는 Style Examples를 참조하세요.

다음 조건 중 하나라도 만족하면 직렬화는 serializedValue에 유효한 유니코드 문자열로 표현될 수 있습니다:

• 문자 집합을 나타내는 charset 파라미터를 허용하는 미디어 타입으로, 모든 유니코드 인코딩(UTF-8, UTF-16 등)이나 그 유효한 부분집합(예: US-ASCII)을 지정하는 경우.
• URI나 HTTP 필드 같은 형식 또는 문자 기반 미디어 타입이 유니코드 인코딩을 요구하거나 기본값으로 가지며, charset으로 오버라이드되지 않는 경우.
• 모든 파트가 위 조건 중 적어도 하나를 만족하는 합성 포맷(예: multipart/mixed로 구성된 파트들이 application/json과 application/xml; charset=utf-8인 경우).

이 모든 경우에 OAD의 문자 집합(일반적으로 JSON의 상호운용 문자 집합으로서 UTF-8로 가정)은 유니코드 코드 포인트로 변환된 다음 실제 직렬화 문자 집합으로 변환되는 과정이 잘 정의되어야 합니다.

externalValue의 경우 문자 집합이 명시되지 않았거나 형식/미디어 타입 명세로 결정되지 않으면 구현체는 UTF-8을 가정하는 것이 SHOULD 권장됩니다.

툴링 구현체는 예시의 호환성을 자동으로 검증하고, 호환되지 않을 경우 예시 값을 거부할 수 있습니다(MAY). 스키마-준비된 데이터 형식의 예시는 검증이 간단합니다.

직렬화된 예시의 경우 여러 표현이 동일한 데이터를 표현할 수 있는 포맷들이 있으며(부록 B 참조), 어떤 경우에는 직렬화된 예시를 파싱하여 결과 데이터를 검증함으로써 모호성을 제거할 수 있지만, 일부 경우 파싱 자체도 모호할 수 있습니다. 따라서 특정 직렬화 예시의 검증은 본질적으로 최선의 노력을 필요로 함을 주의하세요.

YAML로 작성할 때 dataValue에 JSON 문법을 사용할 수 있습니다(예: noRating 예시). 대부분의 경우에는 데이터 형식만으로 충분합니다.

content:
  application/json:
    schema:
      type: object
      required:
      - author
      - title
      properties:
        author:
          type: string
        title:
          type: string
        rating:
          type: number
          minimum: 1
          maximum: 5
          multipleOf: 0.5
    examples:
      noRating:
        summary: 아직 평점이 없는 작품
        dataValue:
          author: A. Writer
          title: The Newest Book
      withRating:
        summary: 평균 평점이 4.5인 작품
        dataValue:
          author: A. Writer
          title: An Older Book
          rating: 4.5
        serializedValue: |
          {
            "author": "A. Writer",
            "title": "An Older Book",
            "rating": 4.5
          }

완전한 바이너리 데이터는 externalValue를 사용하여 표시합니다:

content:
  image/png:
    schema: {}
    examples:
      Red:
        externalValue: ./examples/2-by-2-red-pixels.png

불리언 값을 직렬화하는 표준이 없기 때문에(부록 B 참조) 이 예시는 해당 파라미터에 대해 dataValue와 serializedValue를 사용하여 불리언이 어떻게 직렬화되는지를 보여줍니다:

name: flag
in: query
required: true
schema:
  type: boolean
examples:
  "true":
    dataValue: true
    serializedValue: flag=true
  "false":
    dataValue: false
    serializedValue: flag=false

operationId는 Operation Object에서 선택적 필드이므로, 참조는 대신 operationRef로 URI 참조를 통해 이루어질 수 있습니다(MAY). 아래 예시들 모두 오퍼레이션의 경로 템플릿이 모호하지 않도록 Paths Object를 통해 식별 가능한 오퍼레이션을 참조한다는 점에 유의하세요.

상대 URI 참조형 operationRef 예시:

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: '#/paths/~12.0~1repositories~1%7Busername%7D/get'
    parameters:
      username: $response.body#/username

비상대(절대) URI operationRef 예시:

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1%7Busername%7D/get
    parameters:
      username: $response.body#/username

operationRef를 사용할 때 JSON Pointer를 URI fragment에서 사용할 경우 이스케이프된 슬래시(~1)가 필요하며, 경로 템플릿의 중괄호 { 및 }는 각각 %7B와 %7D로 URL 인코딩해야 합니다. 위 예시에서 비-인코딩된, 퍼센트-디코드된 경로 템플릿은 /2.0/repositories/{username}가 됩니다.

런타임 표현식은 참조된 값의 타입을 보존합니다. 표현식은 중괄호 {}로 감싸서 문자열 값 안에 포함시킬 수 있습니다.

이들 필드는 content 또는 schema와 함께 사용할 수 있습니다(MAY).

example와 examples 필드는 상호 배타적입니다; 검증 요구사항에 대한 안내는 Working with Examples를 참조하세요.

이 객체는 MAY Specification Extensions로 확장될 수 있습니다.

단순한 시나리오의 경우, schema와 style로 헤더의 구조와 문법을 설명할 수 있습니다.

schema로 헤더를 직렬화할 때는 URI 퍼센트 인코딩을 적용해서는 안 됩니다(MUST NOT); 자동으로 이를 적용하는 RFC6570 구현을 사용하는 경우 사용 전에 이를 제거해야 합니다(MUST). 구현체는 헤더 값을 자동으로 따옴표로 감싸려 하기보다는 있는 그대로 전달해야 합니다. 헤더의 따옴표 규칙은 헤더마다 매우 다양하기 때문입니다. 따옴표 및 이스케이프에 대한 지침은 Appendix D를 참조하세요.

추가 안내는 Appendix C: Using RFC6570-Based Serialization를 참조하세요.

더 복잡한 시나리오의 경우, content 필드는 헤더의 미디어 타입과 스키마를 정의하고 사용 예시를 제공할 수 있습니다.

JSON Schema Validation 명세에서 정의한 바와 같이, 데이터 타입은 선택적 수정 키워드인 format을 가질 수 있습니다. 해당 명세에 따라 format은 기본적으로 검증을 수행하지 않는 주석으로 취급됩니다; format을 검증하는 능력은 구현마다 다릅니다.

OpenAPI Initiative는 OAS 사용자 및 다른 명세에서 정의한 포맷을 위한 포맷 레지스트리를 호스팅합니다. 등록된 포맷에 대한 지원은 엄격히 OPTIONAL이며, 하나의 등록된 포맷을 지원한다고 해서 다른 포맷도 지원함을 의미하지 않습니다.

format 키워드가 없는 타입은 JSON Schema의 타입 정의를 따릅니다. 특정 format을 인식하지 못하는 도구는 MAY 포맷 없이 type만을 기준으로 동작할 수 있습니다. JSON Schema 검증의 목적상 각 포맷은 적용되는 JSON 데이터 타입 집합을 지정해야 합니다. 이 레지스트리에서는 이러한 타입이 "JSON Data Type" 열에 표시됩니다.

OAS에서 정의된 포맷은 다음과 같습니다:

앞서 데이터 타입에서 언급했듯이, type: number와 type: integer는 데이터 모델에서 모두 숫자로 간주됩니다.

JSON으로 직렬화된 데이터는 데이터 형태와 거의 동일합니다. 이는 JSON Schema 데이터 모델이 JSON 표현과 거의 동등하기 때문입니다. 예를 들어 직렬화된 UTF-8 JSON 문자열 {"when": "1985-04-12T23:20:50.52"}는 이름이 when인 문자열 값 1985-04-12T23:20:50.52를 갖는 객체를 나타냅니다.

정확한 애플리케이션 형태는 이 규격의 범위를 벗어나지만, 다음 스키마 예로 설명할 수 있습니다:

type: object
properties:
  when:
    type: string
    format: date-time

일부 애플리케이션은 이 문자열을 언어에 관계없이 문자열로 유지할 수 있고, 다른 애플리케이션은 format을 감지하여 Python에서는 datetime.datetime 인스턴스, Java에서는 java.time.ZonedDateTime으로 사용할 수 있습니다. 이 규격은 데이터가 스키마에 따라 유효함을 요구하며, 주석을 통한 확장 검증과 같이 format 같은 주석이 JSON Schema 명세에 따라 제공되는 것만을 요구합니다.

비-JSON 직렬화는 대응되는 데이터 형태와 상당히 다를 수 있으며, 파싱을 위해 여러 단계를 요구할 수 있습니다.

예를 들어 이전의 "when" 예를 application/x-www-form-urlencoded로 직렬화하면 ASCII 문자열 when=1985-04-12T23%3A20%3A50.52처럼 보입니다. 이 예는 여전히 모두 문자열 데이터이기 때문에 간단합니다. JSON과의 차이는 URI 퍼센트 인코딩과 구분자 문법(=가 JSON 문법 및 인용 대신 사용)뿐입니다.

그러나 많은 비-JSON 텍스트 기반 포맷은 복잡할 수 있으며, 텍스트를 올바르게 스키마 준비된 데이터 구조로 파싱하려면 적절한 스키마들을 검사해야 할 수 있습니다. 이러한 포맷으로 직렬화하려면 유효화된 데이터를 사용하거나 동일한 스키마 검사를 수행해야 합니다.

스키마를 검사할 때, 시작 스키마가 주어지면 구현체는 MUST 해당 스키마와 그로부터 $ref와 allOf 키워드만을 따라 도달할 수 있는 모든 스키마를 검사해야 합니다. 이러한 스키마들은 어떤 인스턴스에도 적용되는 것으로 보장됩니다. 스키마에서 type을 찾을 때, type 키워드의 값이 타입 목록이고 직렬화된 값이 목록 내의 둘 이상의 타입으로 성공적으로 파싱될 수 있으며, 다른 발견 가능한 type 키워드가 실제 요구 타입을 명확히 하지 않는 경우, 동작은 구현에 의해 정의됩니다. type을 포함하지 않는 스키마 객체는, 다른 키워드가 존재하더라도 모든 타입을 허용하는 것으로 간주되어야 합니다 (예: maximum는 숫자에 적용되지만 인스턴스가 숫자임을 요구하지는 않습니다).

구현체는 oneOf 또는 $dynamicRef 같은 다른 키워드의 서브스키마나 가능한 참조 대상을 검사할 수는 있으나 (MAY), 모호성을 해결하려 해서는 안 됩니다 (MUST NOT). 예를 들어, 구현체가 anyOf를 검사하기로 선택하면 다음 스키마는:

anyOf:
- type: number
  minimum: 0
- type: number
  maximum: 100

명확하게 숫자 타입을 나타내지만, 다음 스키마는:

anyOf:
- type: number
- maximum: 100

모호합니다. 두 번째 서브스키마는 모든 타입을 허용하기 때문입니다.

스키마 검색 요구사항이 제한적이므로, 검증된 데이터에 접근할 수 있는 직렬화기는 가능하면 데이터를 검사해야 합니다 (MUST); 런타임 데이터를 다루지 않거나 검증된 데이터에 접근할 수 없는 구현체(예: 코드 생성기)는 스키마 검사를 사용해야 합니다.

JSON Schema에서 특정 타입에 적용되는 키워드(예: pattern는 문자열에, minimum은 숫자에 적용)는 데이터가 실제로 그 타입일 것을 요구하거나 암시하지 않는다는 점을 다시 상기하십시오.

다음은 이러한 프로세스의 예제로, 다음 OpenAPI 컴포넌트가 주어졌을 때:

components:
  requestBodies:
    Form:
      content:
        application/x-www-form-urlencoded:
          schema:
            $ref: "#/components/schemas/FormData"
          encoding:
            extra:
              contentType: application/xml
  schemas:
    FormData:
      type: object
      properties:
        code:
          allOf:
          - type: [string, number]
            pattern: "1"
            minimum: 0
          - type: string
            pattern: "2"
        count:
          type: integer
        extra:
          type: object

그리고 아래 요청 본문을 데이터 형태로 파싱해야 한다고 하면:

code=1234&count=42&extra=%3Cinfo%3Eabc%3C/info%3E

우리는 먼저 스키마에서 properties 또는 다른 프로퍼티 정의 키워드를 찾아야 하며, 각 프로퍼티 스키마를 해당 프로퍼티의 type 키워드를 검색하기 위한 시작점으로 사용해야 합니다(정확한 순서는 구현에 따라 다름):

• #/components/requestBodies/Form/content/application~1x-www-form-urlencoded/schema (초기 시작 스키마, 오직 $ref만 있음)
• #/components/schemas/FormData ($ref를 따라가며 properties를 찾음)
• #/components/schemas/FormData/properties/code (code 프로퍼티의 시작점 스키마)
• #/components/schemas/FormData/properties/code/allOf/0 (allOf를 따라가며 type: [string, number]를 찾음)
• #/components/schemas/FormData/properties/code/allOf/1 (allOf를 따라가며 type: string를 찾음)
• #/components/schemas/FormData/properties/count (count 프로퍼티의 시작점 스키마, type: integer를 찾음)
• #/components/schemas/FormData/properties/extra (extra 프로퍼티의 시작점 스키마, type: object를 찾음)

code에 대해서는 먼저 모호한 type을 발견했지만, 이후에 하나의 가능성만 유효하도록 하는 다른 type 키워드를 발견했습니다.

이 검사를 통해 code는 숫자처럼 보이지만 문자열인 것으로 판단되고, count는 스키마 검증 이전에 숫자로 파싱되어야 한다는 것을 알게 됩니다. 또한 extra 문자열은 실제로 info 프로퍼티를 포함하는 객체의 XML 직렬화라는 것도 알 수 있습니다. 이는 이 직렬화의 데이터 형태가 다음 JSON 객체와 동등하다는 것을 의미합니다:

{
  "code": "1234",
  "count": 42
  "extra": {
    "info": "abc"
  }
}

이 객체를 직렬화하려면 또한 프로퍼티를 인코딩 객체와 연관시켜야 하며, 기본 contentType 값을 결정하기 위해 검사가 필요할 수 있습니다. 검증된 데이터에 접근할 수 없다면, 스키마 검사 과정은 파싱을 위한 경우와 동일합니다.

이 예에서 code와 count는 원시 타입이고 encoding 필드에 나타나지 않으므로 일반 텍스트로 직렬화됩니다. 그러나 extra 필드는 객체로 기본적으로 JSON으로 직렬화되지만, encoding 필드의 extra 항목은 이를 XML로 직렬화하라고 지시합니다.

OAS는 원시(raw) 또는 인코딩된(encoded) 바이너리 데이터를 설명할 수 있습니다.

• 원시 바이너리는 전체 HTTP 메시지 본문으로 바이너리 페이로드를 보내거나 바이너리 파트를 허용하는 multipart/* 페이로드의 일부로 사용할 때와 같이 인코딩되지 않은 바이너리 데이터를 허용하는 경우에 사용됩니다.
• 인코딩된 바이너리는 application/json 또는 application/x-www-form-urlencoded와 같은 텍스트 전용 포맷에 바이너리 데이터가 포함될 때 사용됩니다(메시지 본문 또는 URL 쿼리 문자열 모두 해당).

다음 표는 스키마 객체 키워드를 바이너리 데이터에 사용하는 방법을 보여주며, 예제로 image/png를 사용합니다. 모든 바이너리 미디어 타입(예: application/octet-stream)은 바이너리 콘텐츠를 나타내기에 충분합니다.

contentEncoding로 표시된 인코딩은 데이터를 7비트 ASCII 텍스트로 표현하기 위해 크기를 늘리는 것이며, 이는 HTTP의 Content-Encoding 헤더(메시지 본문이 압축되었는지 여부 및 압축 방법을 나타내며 이 섹션에서 설명된 모든 콘텐츠 직렬화 이후에 적용됨)와는 관련이 없습니다. HTTP는 인코딩되지 않은 바이너리 메시지 본문을 허용하므로 전체 메시지 본문에 대한 base64 같은 인코딩을 표기하는 표준화된 HTTP 헤더는 없습니다.

base64url를 contentEncoding으로 사용하면 쿼리 문자열 및 application/x-www-form-urlencoded 유형의 메시지 본문에 필요한 URL 인코딩이 이미 인코딩된 바이너리 데이터를 추가로 인코딩할 필요가 없습니다.

contentMediaType 키워드는 미디어 타입이 이미 설정되어 있으면 중복입니다:

• 미디어 타입 객체의 키로서
• encoding 객체의 contentType 필드에서

스키마 객체가 OAS를 인식하지 못하는 JSON Schema 구현체에 의해 처리될 경우, 중복이더라도 contentMediaType을 포함하는 것이 유용할 수 있습니다. 그러나 contentMediaType이 관련 미디어 타입 객체나 인코딩 객체와 모순되면 contentMediaType은 무시되어야 합니다 (SHALL).

스트리밍 바이너리 페이로드에 대한 지침은 완전 콘텐츠 대 스트리밍 콘텐츠를 참조하십시오.

format 키워드(기본 format-annotation 어휘 사용 시)와 contentMediaType, contentEncoding, 및 contentSchema 키워드는 데이터에 대한 제약을 정의하지만, 직접적으로 검증되는 대신 주석으로 취급됩니다. 확장 검증은 이러한 제약을 강제할 수 있는 한 방법입니다 (MAY).

readOnly 및 writeOnly 키워드는 주석입니다. JSON Schema는 검증하는 데이터가 어떻게 사용되는지 알지 못합니다. 이러한 키워드의 검증은 주석, 읽기/쓰기 방향, (관련 있는 경우) 필드의 현재 값을 확인하여 수행할 수 있습니다 (MAY). JSON Schema Validation Draft 2020-12 섹션 9.4는 이러한 키워드의 기대 동작을 정의하며, 리소스(“소유 권한자”로 설명)는 MAY readOnly 필드를 무시하거나 오류로 처리할 수 있습니다.

필드가 요구되며 동시에 읽기 전용인 경우, 특히 값이 변경되지 않았다면 PUT에서 readOnly: true 제약을 무시하는 것이 유익할 수 있습니다. 이는 GET에서 필드를 올바르게 요구하면서 동일한 표현 및 스키마를 PUT에도 계속 사용할 수 있게 합니다. 읽기 전용 필드를 제거하는 것은 클라이언트에게 부담이 되며, 특히 JSON 데이터가 복잡하거나 중첩되어 있는 경우 그렇습니다.

readOnly의 동작은 특히 이 사양의 3.0 버전에서 지정된 것과 다르다는 점에 유의하십시오.

OpenAPI 명세는 JSON Schema의 allOf 키워드를 사용하여 모델 정의를 결합하고 확장할 수 있게 하여 모델 구성을 제공합니다. allOf는 개별적으로 검증되지만 함께 단일 객체를 구성하는 객체 정의의 배열을 취합니다.

구성은 모델 확장성을 제공하지만 모델 간 계층을 의미하지는 않습니다.

JSON Schema는 또한 anyOf 및 oneOf 키워드를 제공하여, 각각 배열 내의 스키마 중 적어도 하나 또는 정확히 하나가 유효해야 함을 정의할 수 있게 합니다. allOf의 경우와 마찬가지로, 스키마들은 독립적으로 검증됩니다. 이러한 키워드는 단일 필드가 여러 타입의 값을 허용할 수 있는 다형성을 설명하는 데 사용될 수 있습니다.

OpenAPI 명세는 discriminator 필드를 추가하여 JSON Schema의 다형성 지원을 확장합니다. 이 필드의 값은 판별자 객체입니다. 사용될 때 판별자 객체는 anyOf 또는 oneOf의 어떤 스키마가 모델 구조를 검증할 것으로 예상되는지 힌트를 제공합니다. 판별 속성은 필수로 정의될 수도 있고 선택적으로 정의될 수도 있지만, 선택적 속성으로 정의된 경우 판별자 객체는 판별 속성이 없을 때 어느 스키마가 사용될지 지정하는 defaultMapping 필드를 반드시 포함해야 합니다 (MUST).

상속 인스턴스의 판별 속성 값을 정의하는 방법은 두 가지가 있습니다.

• 스키마 이름을 사용합니다.
• 스키마 이름을 재정의하여 속성을 새로운 값으로 덮어씁니다. 새로운 값이 존재하면 스키마 이름보다 우선합니다.

구현체는 JSON Schema의 동적 참조 기능을 사용하여 제네릭 또는 템플릿 데이터 구조를 정의하는 것을 SHOULD 지원해야 합니다:

• $dynamicAnchor는 $dynamicRef가 해석될 수 있는 가능한 스키마 집합(기본 플레이스홀더 스키마 포함)을 식별합니다.
• $dynamicRef는 스키마 진입점에서 참조까지의 경로에서 첫 번째로 일치하는 $dynamicAnchor로 해석됩니다(데이터 사양에 설명된 대로).

예제는 아래의 스키마 객체 예제 섹션에 포함되어 있으며, 추가 정보는 Learn OpenAPI 사이트의 “Dynamic References” 페이지를 참조하십시오.

스키마 객체의 enum 키워드는 개별 값에 설명이나 다른 정보를 연결하는 것을 허용하지 않습니다.

구현체는 각 서브스키마가 const 키워드와 title 또는 description 같은 주석을 포함하는 oneOf 또는 anyOf를 열거형으로 인식하는 것을 지원할 수 있습니다(MAY). 이 패턴의 정확한 동작은 JSON Schema에서 요구하는 것 이상의 부분은 구현체에 의해 정의됩니다.

xml 필드는 JSON 정의를 XML로 변환할 때 추가 정의를 허용합니다. XML 객체는 사용 가능한 옵션에 대한 추가 정보를 포함합니다.

type: string
format: email

type: object
required:
  - name
properties:
  name:
    type: string
  address:
    $ref: '#/components/schemas/Address'
  age:
    type: integer
    format: int32
    minimum: 0

간단한 문자열-문자열 매핑의 경우:

type: object
additionalProperties:
  type: string

문자열-모델 매핑의 경우:

type: object
additionalProperties:
  $ref: '#/components/schemas/ComplexModel'

oneOf:
  - const: RGB
    title: Red, Green, Blue
    description: Specify colors with the red, green, and blue additive color model
  - const: CMYK
    title: Cyan, Magenta, Yellow, Black
    description: Specify colors with the cyan, magenta, yellow, and black subtractive color model

type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
required:
  - name
examples:
  - name: Puma
    id: 1

components:
  schemas:
    ErrorModel:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
        code:
          type: integer
          minimum: 100
          maximum: 600
    ExtendedErrorModel:
      allOf:
        - $ref: '#/components/schemas/ErrorModel'
        - type: object
          required:
            - rootCause
          properties:
            rootCause:
              type: string

다음 예제는 Pet 모델이 petType 속성으로 구분되는 고양이 또는 개를 나타낼 수 있음을 설명합니다. 각 반려동물 유형은 기본 Pet 모델 외에 다른 속성을 가집니다. petType 속성이 없거나 cat 또는 dog와 일치하지 않으면 인스턴스는 유효하지 않습니다.

components:
  schemas:
    Pet:
      type: object
      properties:
        name:
          type: string
      required:
        - name
        - petType
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
    Cat:
      description: A pet cat
      type: object
      properties:
        petType:
          const: 'cat'
        huntingSkill:
          type: string
          description: The measured skill for hunting
          enum:
            - clueless
            - lazy
            - adventurous
            - aggressive
      required:
        - huntingSkill
    Dog:
      description: A pet dog
      type: object
      properties:
        petType:
          const: 'dog'
        packSize:
          type: integer
          format: int32
          description: the size of the pack the dog is from
          default: 0
          minimum: 0
      required:
        - packSize

다음 예제는 이전 섹션의 예제를 확장하여 Pet 스키마에 판별자 객체를 추가합니다. 판별자 객체는 API 소비자에게 주는 힌트일 뿐이며 스키마의 검증 결과를 변경하지 않음을 유의하십시오.

components:
  schemas:
    Pet:
      type: object
      discriminator:
        propertyName: petType
        mapping:
          cat: '#/components/schemas/Cat'
          dog: '#/components/schemas/Dog'
      properties:
        name:
          type: string
      required:
        - name
        - petType
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
    Cat:
      description: A pet cat
      type: object
      properties:
        petType:
          const: 'cat'
        huntingSkill:
          type: string
          description: The measured skill for hunting
          enum:
            - clueless
            - lazy
            - adventurous
            - aggressive
      required:
        - huntingSkill
    Dog:
      description: A pet dog
      type: object
      properties:
        petType:
          const: 'dog'
        packSize:
          type: integer
          format: int32
          description: the size of the pack the dog is from
          default: 0
          minimum: 0
      required:
        - petType
        - packSize

allOf를 사용하여 다형성 모델을 설명하는 것도 가능합니다. 다음 예제는 판별자 객체와 함께 allOf를 사용하여 다형성 Pet 모델을 설명합니다.

components:
  schemas:
    Pet:
      type: object
      discriminator:
        propertyName: petType
      properties:
        name:
          type: string
        petType:
          type: string
      required:
        - name
        - petType
    Cat: # "Cat" will be used as the discriminating value
      description: A representation of a cat
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            huntingSkill:
              type: string
              description: The measured skill for hunting
              enum:
                - clueless
                - lazy
                - adventurous
                - aggressive
          required:
            - huntingSkill
    Dog: # "Dog" will be used as the discriminating value
      description: A representation of a dog
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            packSize:
              type: integer
              format: int32
              description: the size of the pack the dog is from
              default: 0
              minimum: 0
          required:
            - packSize

components:
  schemas:
    genericArrayComponent:
      $id: fully_generic_array
      type: array
      items:
        $dynamicRef: '#generic-array'
      $defs:
        allowAll:
          $dynamicAnchor: generic-array
    numberArray:
      $id: array_of_numbers
      $ref: fully_generic_array
      $defs:
        numbersOnly:
          $dynamicAnchor: generic-array
          type: number
    stringArray:
      $id: array_of_strings
      $ref: fully_generic_array
      $defs:
        stringsOnly:
          $dynamicAnchor: generic-array
          type: string
    objWithTypedArray:
      $id: obj_with_typed_array
      type: object
      required:
      - dataType
      - data
      properties:
        dataType:
          enum:
          - string
          - number
      oneOf:
      - properties:
          dataType:
            const: string
          data:
            $ref: array_of_strings
      - properties:
          dataType:
            const: number
          data:
            $ref: array_of_numbers

역사적 호환성을 위해, type: "array"인 스키마는 기본적으로 nodeType: "none"으로 설정되어 각 배열 항목의 노드를 부모 노드 바로 아래에 배치합니다. 이는 또한 XML 노드 이름에 정의된 추론된 이름 동작과 일치합니다.

목록을 감싸는 요소를 생성하려면 type: "array" 스키마에 명시적으로 nodeType: "element"를 설정하세요. 이 경우 래핑 요소 또는 항목 요소 중 하나에 명시적 이름을 설정하여 동일한 추론된 이름이 사용되는 것을 피하는 것이 좋습니다. 기대되는 동작에 대한 예제를 참조하세요.

만약 element 노드가 원시 타입(primitive type)을 가지면, 해당 element 노드의 내용에 대한 스키마에 의해 암시적 text 노드가 생성됩니다. 이 노드의 이름은 속성 이름(또는 name 필드)으로 지정됩니다.

요소가 속성과 내용을 모두 가질 경우에는 명시적 text 노드가 필요합니다.

두 개의 text 노드를 인접하게 배치하는 것은 파싱에 모호성을 야기하므로 결과 동작은 구현에 따라 정의됩니다.

XML Object가 없는 기본 문자열 속성 예제입니다. 이 예제에서는 serializedValue를 사용합니다(나머지 예제는 XML 형태를 문법 강조와 함께 보이기 위해 externalValue를 사용합니다):

application/xml:
  schema:
    type: object
    xml:
      name: document
    properties:
      animals:
        type: string
  examples:
    pets:
      dataValue:
        animals: dog, cat, hamster
      serializedValue: |
        <document>
          <animals>dog, cat, hamster</animals>
        </document>

기본 문자열 배열 속성(nodeType의 기본값은 none):

application/xml:
  schema:
    type: object
    xml:
      name: document
    properties:
      animals:
        type: array
        items:
          type: string
  examples:
    pets:
      dataValue:
        animals:
          - dog
          - cat
          - hamster
      externalValue: ./examples/pets.xml