1.1. 표기 규칙

이 문서에서 키워드 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", 그리고 "OPTIONAL"은 여기 표시된 것처럼 모두 대문자로 나타날 때, 그리고 그 경우에만 BCP 14 [RFC2119] [RFC8174]에 설명된 대로 해석됩니다.¶

이 문서에서 "content negotiation" 및 "resource"라는 용어는 [HTTP]에서의 의미로 해석됩니다.¶

이 문서에서 "fragment" 및 "fragment identifier"라는 용어는 [URI]에서의 의미로 해석됩니다.¶

이 문서에서 "presentation", "stream", "YAML document", "representation graph", "tag", "serialization detail", "node", "alias node", "anchor", 그리고 "anchor name"이라는 용어는 [YAML]에서의 의미로 해석됩니다.¶

YAML 코드를 포함하는 그림은 가독성을 높이기 위해 항상 %YAML 지시자로 시작합니다.¶

1.2. 프래그먼트 식별

프래그먼트는 스트림 안의 노드를 식별합니다.¶

"*"로 시작하는 프래그먼트 식별자는 YAML 별칭 노드로 해석됩니다(섹션 1.2.1 참조).¶

단일 문서 YAML 스트림의 경우, 비어 있거나 "/"로 시작하는 프래그먼트 식별자는 JSON Pointer [JSON-POINTER]로 해석되며, 별칭 노드를 순회하면서 YAML 표현 그래프에서 평가됩니다. 특히, 빈 프래그먼트 식별자는 루트 노드를 참조합니다. 이 구문은 JSON 데이터 모델과 상호운용 가능한 노드들로 이루어진 경로 위에 있는 YAML 노드만 참조할 수 있습니다(섹션 3.4 참조).¶

프래그먼트 식별자가 기존 노드를 참조한다고 보장되지는 않습니다. 따라서 애플리케이션은 해결되지 않은 별칭 노드를 어떻게 처리해야 하는지 정의하는 것이 SHOULD입니다.¶

 %YAML 1.2
 ---
 one: &foo scalar
 two: &bar
   - some
   - sequence
   - items
 ...
 %YAML 1.2
 ---
 &document_2
 one: &foo [a, sequence]

2.1. 미디어 타입 application/yaml

YAML의 미디어 타입은 application/yaml입니다. 다음 정보는 이 미디어 타입에 대한 등록 양식 역할을 합니다.¶

타입 이름:

application¶

서브타입 이름:

yaml¶

필수 매개변수:

해당 없음¶

선택적 매개변수:

해당 없음. 인식되지 않은 매개변수는 무시해야 합니다.¶

인코딩 고려사항:

binary¶

보안 고려사항:

이 문서의 섹션 4를 참조하십시오.¶

상호운용성 고려사항:

이 문서의 섹션 3을 참조하십시오.¶

공개된 사양:

[YAML], 이 문서¶

이 미디어 타입을 사용하는 애플리케이션:

동적 프로그래밍 언어의 공통 데이터 타입을 중심으로 설계된, 사람이 읽기 쉽고, 언어 간에 사용할 수 있으며, 유니코드 기반인 데이터 직렬화 언어가 필요한 애플리케이션입니다.¶

프래그먼트 식별자 고려사항:

이 문서의 섹션 1.2를 참조하십시오.¶

추가 정보:

이 타입에 대한 폐기된 별칭 이름:

application/x-yaml, text/yaml, 그리고 text/x-yaml. 이러한 이름들은 사용되고 있지만 등록되어 있지는 않습니다.¶

매직 넘버:

해당 없음¶

파일 확장자:

"yaml"(선호됨) 및 "yml". 이 문서의 섹션 3.3을 참조하십시오.¶

Macintosh 파일 타입 코드:

해당 없음¶

Windows 클립보드 이름:

YAML¶

추가 정보를 위한 연락 담당자 및 이메일 주소:

이 문서의 저자 주소 섹션을 참조하십시오.¶

의도된 사용:

COMMON¶

사용 제한:

없음¶

저자:

이 문서의 저자 주소 섹션을 참조하십시오.¶

변경 관리자:

IETF¶

2.2. +yaml 구조화 구문 접미사

접미사 +yaml은 그 표현이 application/yaml에 대해 확립된 것을 따르는 모든 미디어 타입과 함께 사용될 MAY 있습니다. 구조화 구문 접미사 등록 양식은 다음과 같습니다. 등록 양식의 각 부분 정의는 [MEDIATYPE]을 참조하십시오.¶

이름:

YAML Ain't Markup Language (YAML)¶

+접미사:

+yaml¶

참조:

[YAML], 이 문서¶

인코딩 고려사항:

application/yaml과 동일¶

상호운용성 고려사항:

application/yaml과 동일¶

프래그먼트 식별자 고려사항:

application/yaml과 달리, +yaml에 대해서는 정의된 프래그먼트 식별 구문이 없습니다.¶

특정 xxx/yyy+yaml 미디어 타입은 프래그먼트 식별자에 대한 구문과 의미론을 정의해야 합니다. 명시적으로 표현되지 않는 한 application/yaml에 대해 정의된 것들이 적용되지 않기 때문입니다.¶

보안 고려사항:

application/yaml과 동일¶

연락처:

httpapi@ietf.org 또는 art@ietf.org¶

저자:

이 문서의 저자 주소 섹션을 참조하십시오.¶

변경 관리자:

IETF¶

3.1. YAML은 진화하는 언어

YAML은 진화하는 언어이며, 시간이 지남에 따라 일부 기능은 추가되고 다른 기능은 제거되었습니다.¶

application/yaml 미디어 타입 등록은 YAML 버전과 독립적입니다. 이를 통해 버전 독립적인 YAML 리소스의 콘텐츠 협상이 가능해집니다.¶

특정 YAML 버전과 관련된 기능을 고려하는 구현자는 %YAML 지시자를 사용하여 YAML 문서 안에 이를 지정할 수 있습니다 ([YAML]의 섹션 6.8.1 참조).¶

3.2. YAML 스트림

YAML 스트림은 0개 이상의 YAML 문서를 포함할 수 있습니다.¶

다중 문서 스트림을 수신할 때, 단일 문서 스트림만 예상하는 애플리케이션은 추가 문서를 무시하는 대신 오류를 신호해야 합니다.¶

현재 구현들은 JSON 텍스트 시퀀스([RFC7464] 참조)와 유사하게 스트림 안의 서로 다른 문서를 독립적인 것으로 간주합니다. 앵커와 같은 요소가 서로 다른 문서 간에 참조 가능하다고 보장되지는 않습니다.¶

3.3. 파일명 확장자

"yaml" 파일명 확장자가 선호되는 확장자입니다. 이는 웹에서 가장 널리 사용되고 많이 쓰입니다. "yml" 파일명 확장자도 여전히 사용됩니다. 동일한 문맥에서 두 파일명 확장자를 동시에 사용하는 것은 상호운용성 문제를 일으킬 수 있습니다 (예: "config.yaml"과 "config.yml"이 모두 있는 경우).¶

3.4. YAML과 JSON

플로 컬렉션 스타일([YAML]의 섹션 7.4 참조)을 사용할 때, YAML 문서는 JSON [JSON]처럼 보일 수 있습니다. 따라서 유사한 상호운용성 고려사항이 적용됩니다.¶

JSON으로 소비될 정보를 직렬화하기 위한 더 효율적인 형식으로 YAML을 사용할 때, 표현 그래프에 반영되지 않고 프레젠테이션 또는 직렬화 세부사항으로 분류되는 정보([YAML]의 섹션 3.2 참조)는 폐기될 수 있습니다. 여기에는 주석([YAML]의 섹션 3.2.3.3 참조), 지시자, 그리고 JSON 대응물이 없는 별칭 노드 ([YAML]의 섹션 7.1 참조)가 포함됩니다.¶

 %YAML 1.2
 ---
 # This comment will be lost
 # when serializing in JSON.
 Title:
   type: string
   maxLength: &text_limit 64

 Name:
   type: string
   maxLength: *text_limit  # Replaced by the value 64.

구현자는 처리 중에 관련 정보가 손실되지 않도록 해야 합니다. 예를 들어, 별칭 노드가 정적 값으로 대체되는 것을 허용 가능한 것으로 간주할 수 있습니다.¶

어떤 경우에는 구현자가 허용되는 YAML 기능 목록을 정의하고자 할 수 있으며, 이때 다음 기능들이 [JSON]과 상호운용성 문제가 있을 수 있음을 고려해야 합니다:¶

• 다중 문서 YAML 스트림¶
• 비 UTF-8 인코딩. YAML 스트림을 UTF-16 또는 UTF-32로 인코딩하기 전에, 폐쇄된 생태계의 일부가 아닌 시스템 간에 JSON 텍스트를 교환할 때는 [JSON]의 섹션 8.1이 UTF-8 사용을 의무화하며, [YAML]의 섹션 5.2가 UTF-8 사용을 권장한다는 점을 유의해야 합니다.¶
• 문자열이 아닌 매핑 키¶
• 앵커를 사용해 표현되는 순환 참조(섹션 4.2 및 그림 4 참조)¶
• JSON은 이를 지원하지 않으므로 .inf 및 .nan 부동소수점 값¶
• JSON이 아닌 타입, 여기에는 이전 YAML 버전의 기본 스키마에 포함되었던 !!timestamp와 같은 태그와 연결된 타입이 포함됩니다¶
• 일반적인 태그, 특히 JSON 타입에 매핑되지 않는 태그, 예를 들어 !!python/object 및 !mytag와 같은 사용자 정의 및 로컬 태그([YAML]의 섹션 2.4 참조)¶

 %YAML 1.2
 ---
 non-json-keys:
   0: a number
   [0, 1]: a sequence
   ? {k: v}
   : a map
 ---
 non-json-keys:
   !date 2020-01-01: a timestamp
 non-json-value: !date 2020-01-01
 ...

3.5. 프래그먼트 식별자

프래그먼트 식별자가 별칭 노드를 순회할 수 있도록 하려면, 프래그먼트 식별자 평가 전에 YAML 표현 그래프가 생성되어야 합니다. 이 평가가 무한 루프나 예기치 않은 코드 실행처럼 섹션 3.4 및 4에서 언급한 문제를 일으키지 않도록 하는 것이 중요합니다.¶

구현자는 YAML 버전과 지원되는 기능 (예: 병합 키)이 표현 그래프 생성에 영향을 줄 수 있음을 고려해야 합니다(그림 9 참조).¶

섹션 1.2에서 이 문서는 JSON 데이터 모델을 기반으로 하는 사양의 사용을 YAML 프래그먼트 식별자 지원으로 확장합니다. 이는 YAML로 작성된 OpenAPI 문서 [OAS]와 같은 이미 정착된 관행의 상호운용성을 향상시키기 위한 것입니다.¶

부록 A는 독자가 프래그먼트 식별자와 관련된 상호운용성 문제를 이해하는 데 도움이 되도록 예제의 비포괄적 목록을 제공합니다.¶

4.1. 임의 코드 실행

YAML 태그를 사용할 때는 주의해야 합니다. 그 해석이 예기치 않은 코드 실행을 유발할 수 있기 때문입니다.¶

역직렬화기에서의 코드 실행은 기본적으로 비활성화되어야 하며, 명시적으로만 활성화되어야 합니다. 후자의 경우, 구현은 코드 실행 결과가 엄격하게 제한된 시간/메모리 한도 안에 머무르도록 보장해야 합니다(예: 특정 함수를 통해).¶

많은 구현은 이러한 문제를 다루는 안전한 역직렬화기를 제공합니다.¶

4.2. 리소스 고갈

YAML 문서는 루트가 있고 연결된 방향 그래프이며 참조 순환을 포함할 수 있으므로, 단순한 트리로 취급할 수 없습니다([YAML]의 섹션 3.2.1 참조). 이를 단순한 트리로 취급하는 구현은 YAML 표현 그래프를 순회하는 동안 무한 루프에 빠질 위험이 있습니다. 이는 다음과 같은 경우 발생할 수 있습니다:¶

• 이를 JSON으로 직렬화하려고 할 때, 또는¶
• JSON 데이터 모델을 기반으로 하는 사양 (예: [JSON-POINTER])을 사용해 노드를 검색/식별할 때.¶

 %YAML 1.2
 ---
 x: &x
   y: *x

표현 그래프가 순환적이지 않더라도, 이를 단순한 트리로 취급하면 지수적 데이터 팽창(예: Billion Laughs 공격)을 유발하는 등의 부적절한 동작으로 이어질 수 있습니다.¶

 %YAML 1.2
 ---
 x1: &a1 ["a", "a"]
 x2: &a2 [*a1, *a1]
 x3: &a3 [*a2, *a2]

이는 앵커 재귀 깊이를 제한하고 처리 전에 입력을 검증하는 프로세서를 사용하여 해결할 수 있습니다. 이러한 경우에도 사용하려는 구현을 신중하게 테스트하는 것이 중요합니다. 참조 순환을 지원하지 않는 형식으로 YAML 표현 그래프를 직렬화할 때도 동일한 고려사항이 적용됩니다(섹션 3.4 참조).¶

4.3. YAML 스트림

YAML 스트림의 증분 파싱 및 처리는 부분 결과를 생성하고 이후 스트림 나머지 부분의 파싱 실패를 나타낼 수 있습니다. 부분 처리를 방지하기 위해, 구현자는 스트림 안의 모든 문서를 동시에 검증하고 처리하는 방식을 선호할 수 있습니다.¶

YAML 스트림을 반복적으로 파싱하고 재인코딩하면 문서 구분자(예: --- 또는 ...)가 추가되거나 제거될 수 있고, 앵커 이름 및 기타 직렬화 세부사항이 변경되어 서명 검증이 깨질 수 있습니다.¶

4.4. 불리언 표현

[YAML]의 섹션 10.3.2는 정규 표현식 true|True|TRUE|false|False|FALSE와 일치하는 스칼라만 불리언으로 해석된다고 지정합니다. 이전 YAML 버전은 더 관대했습니다(예: NO 및 N을 False로 해석하고, YES 및 Y를 True로 해석). 이전 구문이 사용되는 경우 YAML 구현은 {insecure: n}을 {insecure: false} 대신 {insecure: "n"}으로 해석할 수 있습니다. [YAML]의 섹션 10.3.2에 정의된 구문을 사용하면 이러한 문제를 방지할 수 있습니다.¶

A.1. 참조할 수 없는 노드

이 예는 매핑 키가 문자열이 아니기 때문에 JSON 데이터 모델을 기반으로 참조할 수 없는 몇 가지 YAML 노드를 보여줍니다.¶

 %YAML 1.2
 ---
 a-map-cannot:
   ? {be: expressed}
   : with a JSON Pointer

 0: no numeric mapping keys in JSON

A.2. 없는 노드 참조

이 예에서 프래그먼트 #/0은 기존 노드를 참조하지 않습니다.¶

 %YAML 1.2
 ---
 0: "JSON Pointer `#/0` references a string mapping key."

A.3. 앵커와 순환 참조가 있는 표현 그래프

이 YAML 문서에서 #/foo/bar/baz 프래그먼트 식별자는 표현 그래프를 순회하여 문자열 you를 참조합니다. 또한 순환 참조가 존재한다는 것은 &anchor 노드를 참조하는 프래그먼트 식별자 #/foo/bat/../bat/bar가 무한히 많음을 의미합니다.¶

 %YAML 1.2
 ---
 anchor: &anchor
   baz: you
 foo: &foo
   bar: *anchor
   bat: *foo

많은 YAML 구현은 YAML 1.1에 정의된 병합 키 "<<:"를 표현 그래프에서 해석합니다. 이는 프래그먼트 #/book/author/given_name이 문자열 Federico를 참조하며, 프래그먼트 #/book/<<는 기존 노드를 참조하지 않음을 의미합니다.¶

 %YAML 1.1
 ---
 # Many implementations use merge keys.
 the-viceroys: &the-viceroys
   title: The Viceroys
   author:
     given_name: Federico
     family_name: De Roberto
 book:
   <<: *the-viceroys
   title: The Illusion