6. 診断記法

CBOR はバイナリ交換形式です。ドキュメント化とデバッグを容易にするため、特にデバッグに協力するエンティティ間のコミュニケーションを容易にするため、このセクションでは人間が読める簡単な診断記法を定義します。実際の交換は常にバイナリ形式で行われます。

これは真に診断用の記法であり、解析されることを意図したものではないことに注意してください。したがって、この文書では (ABNF のような) 形式的な定義を与えません。(設定ファイル内で CBOR データ項目を表現するためのテキストベースの形式を探している実装者は、YAML [YAML] も検討するとよいでしょう。)

診断記法は、RFC 4627 で定義されている JSON を大まかにベースとしており、必要な箇所でそれを拡張しています。

この記法は、数値 (整数および浮動小数点)、True (>true<)、False (>false<)、Null (>null<)、UTF-8 文字列、配列、およびマップ (マップは JSON ではオブジェクトと呼ばれます。診断記法はここで JSON を拡張し、キーの位置に任意のデータ項目を置くことを許可します) について JSON の構文を借用しています。Undefined は JavaScript と同様に >undefined< と書かれます。非有限の浮動小数点数 Infinity、-Infinity、および NaN は、この文の中にあるとおりに書かれます (これは JavaScript でも書ける方法の 1 つですが、JSON では認められていません)。タグ付きの項目は、タグの整数値に続けて括弧内に項目を書きます。例えば、RFC 3339 (ISO 8601) の日付は次のように記述できます:

0("2013-03-21T20:04:00Z")

また、同等の相対時刻は次のようになります:

1(1363896240)

バイト文字列は、パディングなしの基底エンコーディングのいずれかで記述され、単一引用符で囲まれ、base16 には >h<、base32 には >b32<、base32hex には >h32<、base64 または base64url には >b64< が前置されます (実際のエンコーディングは重複しないため、文字列は曖昧さのないままです)。例えば、バイト文字列 0x12345678 は h'12345678'、b32'CI2FM6A'、または b64'EjRWeA' と書くことができます。

未割り当てのシンプル値は、括弧内に適切な整数を入れて "simple()" として与えられます。例えば、"simple(42)" は主タイプ 7、値 42 を示します。

6.1. エンコーディング指示子

診断記法において、いくつかの代替表現のうち実際にどれが使われたかを示すと有用な場合があります。例えば、診断デコーダによって >1.5< と書かれたデータ項目は、半精度、単精度、または倍精度の浮動小数点としてエンコードされていた可能性があります。

エンコーディング指示子の慣例は、アンダースコアで始まり、その後ろに続く英数字またはアンダースコアであるすべての文字が、エンコーディング指示子であるというものです。この情報に関心のない者はそれを無視して構いません。エンコーディング指示子は常にオプションです。

データ項目が不定長形式で表現されていたことを示すために、マップの開始波括弧または配列の開始角括弧の後に単一のアンダースコアを書くことができます。例えば、[_ 1, 2] には、データ項目 [1, 2] を表現するのに不定長表現が使われたことを示す指示子が含まれています。

アンダースコアに続く 10 進数字 n は、直前の項目 (配列およびマップの場合は、直前の角括弧または波括弧で始まる項目) が追加情報値 24+n でエンコードされていたことを示します。例えば、1.5_1 は半精度浮動小数点数であり、1.5_3 は倍精度でエンコードされています。このエンコーディング指示子は付録 A には示されていません。(なお、エンコーディング指示子 "_" はこのように完全形 "_7" の省略形であり、後者は使用されません。)

特殊なケースとして、不定長のバイト文字列およびテキスト文字列は、(_ h'0123', h'4567') および (_ "foo", "bar") の形式で記述できます。