3. Specification of the CBOR Encoding (CBOR エンコーディング仕様)

CBOR データ項目 (セクション 2) は, このセクションで説明されているように, 整形式のエンコードされたデータ項目を運ぶバイト文字列にエンコードされるか, またはそこからデコードされます. エンコーディングは, 附録 B の表 7 で要約されており, 初期バイトでインデックス化されています. エンコーダは整形式のエンコードされたデータ項目のみを生成しなければなりません. デコーダは, 整形式のエンコードされた CBOR データ項目ではない入力に遭遇したときに, デコードされたデータ項目を返してはなりません (これは, 損傷したエンコードされた CBOR データ項目からいくつかの情報を利用可能にする可能性のある診断および回復ツールの有用性を損なうものではありません).

各エンコードされたデータ項目の初期バイトには, 主要型 (Major Type, 上位 3 ビット, セクション 3.1 で説明) と追加情報 (Additional Information, 下位 5 ビット) の両方に関する情報が含まれています. いくつかの例外を除いて, 追加情報の値は符号なし整数 "引数" (argument) をロードする方法を記述します:

24 未満: 引数の値は追加情報の値です.

24, 25, 26, または 27: 引数の値は, それぞれネットワークバイトオーダーで後続の 1, 2, 4, または 8 バイトに保持されます. 主要型 7 および追加情報値 25, 26, 27 の場合, これらのバイトは整数引数として使用されず, 浮動小数点値として使用されます (セクション 3.3 を参照).

28, 29, 30: これらの値は, CBOR フォーマットへの将来の追加のために予約されています. 現在のバージョンの CBOR では, エンコードされた項目は整形式ではありません.

31: 引数値は導出されません. 主要型が 0, 1, または 6 の場合, エンコードされた項目は整形式ではありません. 主要型 2 から 5 の場合, 項目の長さは不定 (indefinite) であり, 主要型 7 の場合, バイトはデータ項目をまったく構成せず, 不定長項目を終了します; これらはすべてセクション 3.2 で説明されています.

初期バイトと引数を構築するために消費される追加のバイトは, 総称してデータ項目の ヘッド (head) と呼ばれます.

この引数の意味は主要型に依存します. たとえば, 主要型 0 では, 引数はデータ項目自体の値です (主要型 1 では, データ項目の値は引数から計算されます); 主要型 2 と 3 では, 後続する文字列データのバイト長を示します; 主要型 4 と 5 では, 含まれるデータ項目の数を決定するために使用されます.

エンコードされたバイトシーケンスがデータ項目の終了前に終了する場合, その項目は整形式ではありません. エンコードされたバイトシーケンスが最外部のエンコードされた項目がデコードされた後もバイトが残っている場合, そのエンコーディングは単一の整形式 CBOR 項目ではありません. アプリケーションに応じて, デコーダはエンコーディングを整形式でないものとして扱うか, 残りのバイトの開始位置をアプリケーションに識別するだけです.

CBOR デコーダ実装は, 初期バイトのすべての 256 の定義された値を持つジャンプテーブル (表 7) に基づくことができます. 制約された実装のデコーダは, 代わりに初期バイトと後続のバイトの構造を使用して, よりコンパクトなコードにすることができます (これがどのように見えるかについての大まかな印象については, 附録 C を参照してください).

3.1. Major Types (主要型)

以下は, 主要型と, その型に関連付けられた追加情報およびその他のバイトをリストしています.

主要型 0: 範囲 0..2^(64)-1 (両端を含む) の符号なし整数. エンコードされた項目の値は引数自体です. たとえば, 整数 10 は 1 バイト 0b000_01010 (主要型 0, 追加情報 10) として表されます. 整数 500 は 0b000_11001 (主要型 0, 追加情報 25) の後に 2 バイト 0x01f4 が続き, これは 10 進数で 500 です.

主要型 1: 範囲 -2^(64)..-1 (両端を含む) の負の整数. 項目の値は -1 から引数を引いたものです. たとえば, 整数 -500 は 0b001_11001 (主要型 1, 追加情報 25) の後に 2 バイト 0x01f3 が続き, これは 10 進数で 499 です.

主要型 2: バイト文字列 (Byte String). 文字列内のバイト数は引数と等しくなります. たとえば, 長さが 5 のバイト文字列は, 初期バイト 0b010_00101 (主要型 2, 長さの追加情報 5) の後に 5 バイトのバイナリコンテンツが続きます. 長さが 500 のバイト文字列は, 3 つの初期バイト 0b010_11001 (主要型 2, 2 バイト長を示す追加情報 25) の後に長さ 500 の 2 バイト 0x01f4 が続き, その後に 500 バイトのバイナリコンテンツが続きます.

主要型 3: UTF-8 [RFC3629] としてエンコードされたテキスト文字列 (Text String, セクション 2). 文字列内のバイト数は引数と等しくなります. 無効な UTF-8 シーケンスを含む文字列は整形式ですが無効です (セクション 1.2). このタイプは, 人間が読めるテキストを解釈または表示する必要があるシステムのために提供され, 非構造化バイトと指定されたレパートリー (Unicode) およびエンコーディング (UTF-8) を持つテキストを区別できるようにします. JSON などのフォーマットとは対照的に, このタイプの Unicode 文字はエスケープされません. したがって, 改行文字 (U+000A) は常に文字列内でバイト 0x0a として表現され, バイト 0x5c6e (文字 "" と "n") または 0x5c7530303061 (文字 "", "u", "0", "0", "0", "a") として表現されることはありません.

主要型 4: データ項目の配列 (Array). 他のフォーマットでは, 配列はリスト (lists), シーケンス (sequences), またはタプル (tuples) とも呼ばれます ("CBOR シーケンス" はやや異なるものですが [RFC8742]). 引数は配列内のデータ項目の数です. 配列内の項目はすべて同じ型である必要はありません. たとえば, 任意の型の 10 個の項目を含む配列は, 初期バイト 0b100_01010 (主要型 4, 長さの追加情報 10) の後に残りの 10 個の項目が続きます.

主要型 5: データ項目のペアのマップ (Map). マップは, テーブル (tables), 辞書 (dictionaries), ハッシュ (hashes), またはオブジェクト (objects, JSON で) とも呼ばれます. マップはデータ項目のペアで構成され, 各ペアはキー (key) とそれに続く値 (value) で構成されます. 引数はマップ内のデータ項目の ペア の数です. たとえば, 9 つのペアを含むマップは, 初期バイト 0b101_01001 (主要型 5, ペア数の追加情報 9) の後に残りの 18 個の項目が続きます. 最初の項目は最初のキー, 2 番目の項目は最初の値, 3 番目の項目は 2 番目のキー, というように続きます. マップ内の項目はペアで提供されるため, その総数は常に偶数です: 奇数の項目を含むマップ (最後のキーデータ項目の後に値データが存在しない) は整形式ではありません. 重複するキーを持つマップは整形式である可能性がありますが, 有効ではなく, したがって不確定なデコーディングを引き起こします; セクション 5.6 も参照してください.

主要型 6: タグ付きデータ項目 ("タグ", Tag). そのタグ番号 (Tag Number) は範囲 0..2^(64)-1 (両端を含む) の整数で引数であり, その含まれるデータ項目 (タグコンテンツ, tag content) はヘッドに続く単一のエンコードされたデータ項目です. セクション 3.4 を参照してください.

主要型 7: 浮動小数点数と簡易値 (Simple Values), および "break" 停止コード. セクション 3.3 を参照してください.

これら 8 つの主要型により, データ項目の初期バイトの 256 の可能な値のうちどれが使用されるかを示す単純な表が得られます (表 7).

主要型 6 と 7 では, 多くの可能な値が将来の仕様のために予約されています. これらの値の詳細については, セクション 9 を参照してください.

表 1 は, CBOR によって定義された主要型を要約しており, 今のところセクション 3.2 を無視しています. この表の数値 N は引数を表します.

主要型	意味	コンテンツ
0	符号なし整数 N	-
1	負の整数 -1-N	-
2	バイト文字列	N バイト
3	テキスト文字列	N バイト (UTF-8 テキスト)
4	配列	N 個のデータ項目 (要素)
5	マップ	2N 個のデータ項目 (キー/値ペア)
6	番号 N のタグ	1 個のデータ項目
7	簡易値/浮動小数点	-

表 1: CBOR 主要型の定長使用の概要 (N = 引数)

3.2. Indefinite Lengths for Some Major Types (一部の主要型の不定長)

4 つの CBOR 項目 (配列, マップ, バイト文字列, テキスト文字列) は, 追加情報値 31 を使用して不定長でエンコードできます. これは, 配列またはマップ内の項目数, または文字列の全長が既知である前に項目のエンコーディングを開始する必要がある場合に便利です. (そのデータ項目のすべてが既知である前にデータ項目の送信を開始する能力は, そのデータ項目内の "ストリーミング" (streaming) と呼ばれることがよくあります).

不定長配列とマップは, 不定長文字列 (バイト文字列とテキスト文字列) とは異なる方法で処理されます.

3.2.1. The "break" Stop Code ("break" 停止コード)

"break" 停止コードは, 主要型 7 と追加情報値 31 (0b111_11111) でエンコードされます. これ自体はデータ項目ではありません: 不定長項目を閉じるための単なる構文的特徴です.

"break" 停止コードが, 不定長文字列, 配列, またはマップの直接内部以外の, データ項目が予期される場所に現れる場合 -- たとえば, 定長配列またはマップの直接内部 -- 含まれる項目は整形式ではありません.

3.2.2. Indefinite-Length Arrays and Maps (不定長配列とマップ)

不定長配列とマップは, その主要型と追加情報値 31 を使用して表され, 配列の場合はゼロ個以上の項目の任意長シーケンス, マップの場合はキー/値ペアが続き, その後 "break" 停止コード (セクション 3.2.1) が続きます. 言い換えれば, 不定長配列とマップは, 追加情報値 31 で始まり "break" 停止コードで終わることを除いて, 他の配列やマップと同じように見えます.

"break" 停止コードがマップ内のキーの後, そのキーの値の代わりに現れる場合, マップは整形式ではありません.

不定長配列またはマップ項目のネストに制限はありません. "break" は単一の項目のみを終了するため, ネストされた不定長項目には, 不定長項目を開始する型バイトの数とまったく同じ数の "break" 停止コードが必要です.

3.3. Floating-Point Numbers and Values with No Content (浮動小数点数とコンテンツのない値)

主要型 7 は 2 種類のデータ用です: 浮動小数点数とコンテンツを必要としない "簡易値" (Simple Values). 初期バイトの 5 ビット追加情報の各値には, 表 3 で定義されているように, それぞれ独自の意味があります. 整数の主要型と同様に, この主要型の項目はコンテンツデータを運びません; すべての情報は初期バイト (ヘッド) 内にあります.

5 ビット値	セマンティクス
0..23	簡易値 (値 0..23)
24	簡易値 (後続のバイトの値 32..255)
25	IEEE 754 半精度浮動小数点 (16 ビットが続く)
26	IEEE 754 単精度浮動小数点 (32 ビットが続く)
27	IEEE 754 倍精度浮動小数点 (64 ビットが続く)
28-30	予約済み, 本文書では整形式ではない
31	不定長項目の "break" 停止コード (セクション 3.2.1)

表 3: 主要型 7 の追加情報の値

他のすべての主要型と同様に, 5 ビット値 24 は 1 バイト拡張を示します: 簡易値を表すために追加のバイトが続きます. (混乱を最小限に抑えるために, 値 32 から 255 のみが使用されます.) これにより, 初期バイトの構造が維持されます: 他の主要型と同様に, これらの長さは常に最初のバイトの追加情報に依存します. 表 4 は, 簡易値に割り当てられ, 利用可能な数値をリストしています.

値	セマンティクス
0..19	(未割り当て)
20	false
21	true
22	null
23	undefined
24..31	(予約済み)
32..255	(未割り当て)

表 4: 簡易値

エンコーダは, 0xf8 (主要型 7, 追加情報 24) で始まり, 0x20 (32 進数) 未満のバイトが続く 2 バイトシーケンスを発行してはなりません. そのようなシーケンスは整形式ではありません. (これは, エンコーダが "false", "true", "null", または "undefined" を 2 バイトシーケンスでエンコードできないこと, およびこれらの 1 バイトバリアントのみが整形式であることを意味します; より一般的に言えば, 各簡易値には単一の表現バリアントしかありません).

5 ビット値 25, 26, 27 は, 16 ビット, 32 ビット, 64 ビットの IEEE 754 バイナリ浮動小数点値 [IEEE754] 用です. これらの浮動小数点値は, 適切なサイズの追加バイトにエンコードされます. (16 ビット浮動小数点数に関するいくつかの情報については, 附録 D を参照してください.)

3.4. Tagging of Items (項目のタグ付け)

CBOR では, データ項目をタグ (tag) で囲んで追加のセマンティクスを与えることができます. これは タグ番号 (tag number) によって一意に識別されます. タグは主要型 6 で, その引数 (セクション 3) はタグ番号を示し, 単一の含まれるデータ項目, つまり タグコンテンツ (tag content) を含みます. (タグがそのコンテンツにさらなる構造を必要とする場合, この構造は含まれるデータ項目によって提供されます.) タグ番号とタグコンテンツの両方で構成される全体のデータ項目に対して タグ という用語を使用します: タグコンテンツはタグ付けされているデータ項目です.

たとえば, 長さ 12 のバイト文字列に番号 2 のタグが付けられて, それが符号なし 大数 (bignum, セクション 3.4.3) であることを示すとします. エンコードされたデータ項目は, バイト 0b110_00010 (主要型 6, タグ番号の追加情報 2) で始まり, その後にエンコードされたタグコンテンツが続きます: 0b010_01100 (主要型 2, 長さの追加情報 12) の後に大数の 12 バイトが続きます.

拡張汎用データモデルでは, タグ番号の定義はタグ番号で伝達される追加のセマンティクスを記述します. これらのセマンティクスには, 一部のタグ付きデータ項目と他のデータ項目の等価性が含まれる場合があります. これには, 基本汎用データモデルで表現できるものも含まれます. たとえば, 0xc24101, タグコンテンツが単一バイト 0x01 のバイト文字列である大数は, 整数 1 と等価であり, これは 0x01, 0x1801, または 0x190001 としてもエンコードできます. タグ定義は, 汎用エンコーダに推奨される優先シリアライゼーション (セクション 4.1) を指定する場合があります; これは, タグを使用する表現よりも基本汎用データモデル表現を優先する場合があります.

タグ定義は通常, そのようなタグに対してどのネストされたデータ項目が有効かを定義します. タグ定義は, このドキュメントで定義されているタグのように, そのコンテンツを非常に特定の構文構造に制限する場合もあれば, そのコンテンツをよりセマンティックに定義する場合もあります. 後者の例は, タグ 40 と 1040 が配列を表現する複数の方法を受け入れる方法です [RFC8746].

慣習として, 多くのタグはタグコンテンツとして "null" または "undefined" 値を受け入れません; 代わりに, "null" または "undefined" 値がタグ全体の代わりに使用できることが期待されます; セクション 3.4.2 は, アプリケーションプロトコルおよびプラットフォーム型へのマッピングにおけるこの慣習の処理に関する 1 つの特定のタグについてのいくつかのさらなる考慮事項を提供します.

デコーダは, すべてのタグ番号のタグを理解する必要はなく, 特定の CBOR データ項目を作成する実装とそのストリームをデコードする実装がデータフロー内の各項目のセマンティック意味を知っているアプリケーションでは, タグの価値はほとんどない場合があります. この仕様におけるタグの主な目的は, 日付などの一般的なデータ型を定義することです. 二次的な目的は, CBOR データ項目を異なる形式に変換する必要があることが予見される場合に, 項目のコンテンツに関するヒントを必要とする変換ヒントを提供することです. タグのセマンティクスを理解することは, デコーダにとってオプションです; タグの追加のセマンティクスを解釈せずに, タグ番号とタグコンテンツの両方をアプリケーションに提示するだけで済みます.

タグは, それが囲むデータ項目にセマンティクスを適用します. タグはネストできます: タグ A がタグ B を囲み, タグ B がデータ項目 C を囲む場合, タグ A はデータ項目 C にタグ B を適用した結果に適用されます.

IANA は, セクション 9.2 で説明されているようにタグ番号のレジストリを維持しています. 表 5 は, [RFC7049] で定義されたタグ番号のリストを提供しており, このセクションの残りの部分で定義されています. (タグ番号 35 も [RFC7049] で定義されました; このタグ番号の議論はセクション 3.4.5.3 に続きます.) [RFC7049] の公開以降, 他の多くのタグ番号が定義されていることに注意してください; 完全なリストについては, セクション 9.2 で説明されているレジストリを参照してください.

タグ	データ項目	セマンティクス
0	テキスト文字列	標準日付/時刻文字列; セクション 3.4.1 参照
1	整数または浮動小数点	エポックベースの日付/時刻; セクション 3.4.2 参照
2	バイト文字列	符号なし大数; セクション 3.4.3 参照
3	バイト文字列	負の大数; セクション 3.4.3 参照
4	配列	10 進分数; セクション 3.4.4 参照
5	配列	大浮動小数点数; セクション 3.4.4 参照
21	(任意)	base64url エンコーディングへの予想変換; セクション 3.4.5.2 参照
22	(任意)	base64 エンコーディングへの予想変換; セクション 3.4.5.2 参照
23	(任意)	base16 エンコーディングへの予想変換; セクション 3.4.5.2 参照
24	バイト文字列	エンコードされた CBOR データ項目; セクション 3.4.5.1 参照
32	テキスト文字列	URI; セクション 3.4.5.3 参照
33	テキスト文字列	base64url; セクション 3.4.5.3 参照
34	テキスト文字列	base64; セクション 3.4.5.3 参照
36	テキスト文字列	MIME メッセージ; セクション 3.4.5.3 参照
55799	(任意)	自己記述 CBOR; セクション 3.4.6 参照

表 5: RFC 7049 で定義されたタグ番号