@cbortech/cbor 0.26.5 → 0.26.7

package/README.ja.md

@@ -6,13 +6,13 @@
 [![license](https://img.shields.io/npm/l/%40cbortech%2Fcbor)](./LICENSE)
 ![platform](https://img.shields.io/badge/platform-Node.js%20%7C%20Browser-blue)
 
-[CBOR](#準拠している仕様)、[CDN (CBOR-EDN)](#準拠している仕様)、JavaScript 値を相互変換するための TypeScript ライブラリです。
-
-![CBOR、CDN、JavaScript 値の関係図](./assets/cbor-cdn-js.png)
+[CBOR](#準拠している仕様)、[CDN (CBOR-EDN)](#準拠している仕様)、JavaScript 値の相互変換に加え、[CDDL](#準拠している仕様) スキーマのパース・整形・検証に対応する TypeScript ライブラリです。
 
 プレイグラウンドを **https://cbor.tech/cbor/** で公開しています。
 
-このパッケージは `CBOR` ファサードに加えて、extension の実装に必要な CBOR AST ノードクラス用の entrypoint を公開します。
+![CBOR、CDN、JavaScript 値の関係図](./assets/cbor-cdn-js.png)
+
+このパッケージは CBOR ファサードに加えて、tooling や extension 向けに CDN、CDDL、AST の各 entrypoint を公開します。
 低レベルのパーサー、エンコーダー内部は、ドキュメント上の公開 API には含めていません。
 
 ## インストール
@@ -72,6 +72,20 @@ console.log(value);
 // { hello: 'world', n: 42 }
 ```
 
+### CDDL で検証する
+
+CDDLスキーマをコンパイルし、CBOR バイト列、CDN テキスト、`CborItem` AST を検証できます。
+
+```ts
+import { CDDL } from '@cbortech/cbor/cddl';
+
+const schema = CDDL.compile('point = { x: int, y: int }');
+const result = schema.validate('{"x": 12, "y": -3}');
+
+console.log(result.valid);
+// true
+```
+
 ### CBOR Sequence から JavaScript へ
 
 `decodeSeq` は連結された CBOR item を CBOR Sequence として読み取り、各 item を JavaScript 値として yield します。
@@ -316,6 +330,46 @@ CBOR.format('`\\d+`', { preserveRawString: true });
 // '`\\d+`'
 ```
 
+### ダブルクォート文字列の表記を保持する
+
+デフォルトでは、`CBOR.format()` はダブルクォートのテキスト文字列をデコード後の
+値から再エスケープします。そのため `\uXXXX` エスケープはリテラル文字に変換され
+ます。`preserveTextString` を指定すると、連結されていない `"..."` リテラルを
+元のソース表記のまま再出力します。(バッククォートの raw 文字列(`` `...` ``)
+はこのオプションではなく `preserveRawString` の対象です。`+` 連結を経由した
+文字列は、このオプションを指定していても通常どおり正規化されます。)
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+CBOR.format('"caf\\u00e9"');
+// '"café"'
+
+CBOR.format('"caf\\u00e9"', { preserveTextString: true });
+// '"caf\\u00e9"'
+```
+
+### 数値リテラルの表記を保持する
+
+デフォルトでは、`CBOR.format()` は整数・浮動小数点数リテラルを正規化します。
+16進数・8進数・2進数の整数(`0xff`、`0o377`、`0b101`)は10進数に変換され、
+末尾のゼロや冗長なエンコーディング指標のサフィックス(`1.50`、`1.5_1`)は
+省略されます。`preserveNumberFormat` を指定すると、これらのリテラルを元の
+CDN ソース表記のまま再出力します。`intFormat` / `floatFormat` より優先され
+ます。CDN テキストからパースされたリテラルにのみ効果があり、`CBOR.from()`
+で構築した値や CBOR バイト列からデコードした値には効果がありません(通常
+どおりの整形になります)。
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+CBOR.format('{"a": 0xff, "b": 1.50}');
+// '{"a":255,"b":1.5}'
+
+CBOR.format('{"a": 0xff, "b": 1.50}', { preserveNumberFormat: true });
+// '{"a":0xff,"b":1.50}'
+```
+
 ### `+` による文字列連結を保持する
 
 注意: `+` による文字列連結構文は draft-26 で削除されました。この節は legacy
@@ -350,6 +404,110 @@ CBOR.format("h'68' + b64'aQ'", {
 //   b64'aQ'
 ```
 
+### application-string / -sequence 記法を保持する
+
+一部の組み込み拡張(`dt`/`DT`、`ip`/`IP`)は同じ値に対して `prefix'...'`
+(application string)、`` prefix`...` ``(backtick application string)、
+`prefix<<...>>`(application sequence)、生のタグリテラル(`N(...)`)の
+いずれの記法もサポートしていますが、デフォルトでは `CBOR.format()` を呼ぶ
+たびに解決済みの値から `prefix'...'` を再生成します。そのため
+`` DT`1969-07-21T02:56:16Z` `` も `DT<<'1969-07-21T02:56:16Z'>>` も、生の
+タグ記法 `1(1749772800)` さえも、すべて `DT'...'` 記法に正規化され、さら
+に非正規な `DT'...'` の表記(例えば `Z` の代わりに `+00:00` を使った場合
+など)も書き換えられます。`preserveAppSequence` を指定すると、実際に使わ
+れていた表記のまま保持します。`appStrings: false` を同時に指定した場合は
+効果がありません(どちらにせよ元の表記に関わらず生のタグ記法になるため)。
+これらの記法からパースされていない値にも効果はありません。
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+CBOR.format('1(1749772800)');
+// "DT'2025-06-13T00:00:00Z'"
+
+CBOR.format('1(1749772800)', { preserveAppSequence: true });
+// "1(1749772800)"
+
+CBOR.format("DT<<'1969-07-21T02:56:16Z'>>", { preserveAppSequence: true });
+// "DT<<'1969-07-21T02:56:16Z'>>"
+
+CBOR.format('DT`1969-07-21T02:56:16Z`', { preserveAppSequence: true });
+// "DT`1969-07-21T02:56:16Z`"
+```
+
+### 空行を保持する
+
+デフォルトでは、`CBOR.format()` は配列・マップの要素間(および `(_ ...)`
+のチャンク間)の空行を再シリアライズ時に取り除きます。`preserveBlankLines`
+を指定すると、元のソースでその要素の前のどこかに空行があった場合、要素の
+直前に空行を 1 行だけ再出力します。要素をパラグラフのようにまとめる元の
+見た目を、フォーマット後も保てます。元の空行が何行連続していても、出力
+されるのは常に 1 行だけです。判定は要素の位置だけに基づいており、
+`preserveComments` は不要で、コメントを出力するかどうかにも影響されません。
+`indent` を指定して整形出力する場合のみ効果があり、空行を保持する
+コンテナは `inlineLeafContainers` が有効でも常に 1 要素 1 行で出力されます。
+`preserveAll` にも含まれます。
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+const src = `[
+  1,
+  2,
+
+  3
+]`;
+
+CBOR.format(src, { indent: 2 });
+// [
+//   1,
+//   2,
+//   3
+// ]
+
+CBOR.format(src, { indent: 2, preserveBlankLines: true });
+// [
+//   1,
+//   2,
+//
+//   3
+// ]
+```
+
+### 変更を最小限にとどめてフォーマットする
+
+`preserveAll` を指定すると、すべての `preserve*` 系オプションが一括で
+有効になります。たとえばエディタの保存時フォーマットのように、空白・
+インデントだけを変更し、ほとんどのリテラルの元の表記には手を加えずに
+CDN テキストを整形できます(bignum だけは例外です。上記の
+`preserveNumberFormat` の説明を参照してください)。個別のオプションを
+明示的に指定した場合(`false` も含む)は、そちらが `preserveAll` より
+優先されます。
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+CBOR.format('{"a":0xff,"b":1.5_1,"c":b64\'aGk=\'}', {
+  indent: 2,
+  preserveAll: true,
+});
+// {
+//   "a": 0xff,
+//   "b": 1.5_1,
+//   "c": b64'aGk='
+// }
+```
+
+`CBOR.format()` は内部で `fromCDN()` と `toCDN()` の両方に同じオプション
+を渡すため、このオプション一つで済みます。両者を別々に呼び出す場合は、
+コメントはパース時に取り込んでおく必要があるため、`fromCDN()` 側にも
+`preserveAll`(または `preserveComments`)を指定してください。
+
+```ts
+const item = CBOR.fromCDN(text, { preserveAll: true });
+item.toCDN({ preserveAll: true, indent: 2 });
+```
+
 ### CBOR / CDN / hex dump のバリデーション
 
 `validate` は入力の well-formedness と validity を、例外を投げずにチェックします。
@@ -865,12 +1023,63 @@ const lenient = tokenizeLenient('[1, "ab');
 インスタンスで、`offset`・`line`・`column`、判明している場合は `endOffset` を
 保持します。
 
+## CDDL
+
+`@cbortech/cbor/cddl` サブパスには、CDDL のパーサ・コンパイラ・バリデータが
+入っています。CDDL は CBOR データ構造を記述するスキーマ言語です。
+コンパイル済みスキーマで、CBOR バイト列・CDN テキスト・`CborItem` AST を
+検証できます。
+
+```ts
+import { CDDL } from '@cbortech/cbor/cddl';
+
+const schema = CDDL.compile('point = { x: int, y: int }');
+
+console.log(schema.validate('{"x": 12, "y": -3}').valid);
+// true
+```
+
+検証は throw せず結果オブジェクトを返し、失敗時は入力内のパスと入力・
+スキーマ双方のソース位置を報告します。既定では最初のルールを使い、`rule`
+で別の非 generic 型ルールを指定できます。このほか `features`、`maxDepth`、
+`maxSteps` を指定できます。
+
+[RFC 8610](https://www.rfc-editor.org/rfc/rfc8610) の全 control operator と、
+[RFC 9165](https://www.rfc-editor.org/rfc/rfc9165) の `.plus`、`.cat`、
+`.feature` を実装しています。`.feature` の許可名は `features` オプションで
+指定します。`.abnf` などの未対応演算子は `result.warnings` に報告され、
+制約なしで判定されます。
+
+メインの `CBOR` facade でも、`cddl` オプションにコンパイル済みスキーマ
+または CDDL ソーステキストを渡して検証できます。
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+const value = CBOR.parse('{"x": 12, "y": -3}', {
+  cddl: 'point = { x: int, y: int }',
+});
+// { x: 12, y: -3 }
+```
+
+`parse`・`decode`・`encode` などは不一致時に `CddlMismatchError` を throw
+します。`CBOR.validate()` は代わりに `result.cddlErrors` へ収集します。
+検証オプションは `cddlValidationOptions` で渡せます。`cddl` は
+`new CBOR({ cddl: … })` のようにインスタンスのデフォルトにもできます。
+
+`CDDL.compile()` は `CddlSyntaxError` または `CddlSemanticError` を throw
+します。`{ strict: false }` を指定すると、意味上の問題を
+`schema.warnings` に収集できます。コンパイル済みスキーマは
+`schema.format()` で整形できます。同じサブパスから `tokenize`、
+`tokenizeLenient`、`schema.ast`、`schema.rules` も利用できます。
+
 ## 公開 API
 
 ドキュメント化している公開 export は次のとおりです。
 
 - `CBOR`
 - `CdnSyntaxError`
+- `CddlMismatchError`(`cddl` オプションが throw。[CDDL](#cddl) 節を参照)
 
 `CBOR` ファサードからは次にもアクセスできます。
 
@@ -884,38 +1093,34 @@ const lenient = tokenizeLenient('[1, "ab');
 (`tokenize`, `tokenizeLenient`, `Token`, `TokenType`, `EdnComment`)に、
 AST ノードクラスは `@cbortech/cbor/ast` にあります。
 
-## 準拠している仕様
-
-このライブラリは次の仕様を対象にしています。
-
-- [CBOR, RFC 8949](https://www.rfc-editor.org/rfc/rfc8949)
-- [Concise Diagnostic Notation (CDN), draft-ietf-cbor-edn-literals-25](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/25/)
+CDDL コンパイラは `@cbortech/cbor/cddl`
+(`CDDL`, `CddlSchema`, `CddlSyntaxError`, `CddlSemanticError`,
+`CddlMismatchError`, `tokenize`, `tokenizeLenient`, CDDL AST 型)に
+あります。
 
-draft -25 をベースに、
-[draft -26](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/26/)
-の一部仕様も先行して取り込んでいます。
-
-- 文字列連結 extension `t1` / `b1`(§3.4)
-- 不定長文字列 extension `ilbs` / `ilts`(§3.5)
-- `float` extension のデフォルト有効化(§3.7)
-- draft-26 の raw string 規則(§2.5.4): 終端デリミタは開始デリミタと
-  同数のバッククォートに限られ、スペース除去規則がすべてのデリミタ長に
-  適用されます
-
-draft -26 で削除された `+` による文字列連結構文と、非推奨となった
-`(_ ...)` streamstring 構文は、引き続き受理します。CDN は Internet-Draft
-として策定中の仕様であり、今後も変更される可能性がある点に注意して
-ください(たとえば extension 名 `t1` / `b1` は暫定とされています)。
-
-CDN は、CBOR データを人間が読み書きしやすいテキストとして表現するための記法です。
-サンプル、テストベクター、デバッグ、fixture、設定ファイルに近い用途など、CBOR のバイト列をそのまま扱うと読みにくい場面で役立ちます。
-
-通常の配列、マップ、文字列、数値、真偽値、null は JSON に近い見た目で書けます。
-一方で、CBOR 固有の byte string、tag、simple value、不定長 item、文字列以外の map key、
-`dt'2026-05-06T00:00:00Z'` のような application literal も表現できます。
+## 準拠している仕様
 
-CDN は JSON / JSONC の上位互換なので、通常の JSON データやコメント付きの JSON 風データも、
-特別な変換なしに CDN としてパース・整形できます。
+- CBOR
+  - [RFC 8949](https://www.rfc-editor.org/rfc/rfc8949)
+- CDN (CBOR-EDN)
+  - [draft-ietf-cbor-edn-literals-25](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/25/)
+  - [draft-ietf-cbor-edn-literals-26](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/26/)
+- CDDL
+  - [RFC 8610](https://www.rfc-editor.org/rfc/rfc8610)
+  - [RFC 9682](https://www.rfc-editor.org/rfc/rfc9682)
+  - [RFC 9165](https://www.rfc-editor.org/rfc/rfc9165)
+
+補足:
+
+- CDN は draft-26 に準拠しつつ、draft-25 の `(_ ...)` streamstring 構文と
+  `+` による文字列連結構文も引き続きサポートしています。
+- CDDL は RFC 8610 のすべての control operator と、RFC 9165 の `.plus`、
+  `.cat`、`.feature` をサポートしています。
+- RFC 9682 の更新内容である文字列リテラル文法(`\u{...}` を含む)、構文上の
+  空データモデル(ルールなしのモデルはコンパイル時に意味エラー)、非リテラルの
+  `#6.<type>` / `#7.<type>` head number に対応しています。コメントの `PCHAR`
+  検証、単独 CR の改行、EOF で終わるコメントは、collected ABNF よりも意図的に
+  寛容に受理します。
 
 ## ライセンス
 

package/README.md

@@ -7,14 +7,15 @@
 ![platform](https://img.shields.io/badge/platform-Node.js%20%7C%20Browser-blue)
 
 TypeScript library for converting between [CBOR](#specifications),
-[CDN (CBOR-EDN)](#specifications), and JavaScript values.
-
-![Relationship between CBOR, CDN, and JavaScript values](./assets/cbor-cdn-js.png)
+[CDN (CBOR-EDN)](#specifications), and JavaScript values, plus parsing,
+formatting, and validation for [CDDL](#specifications) schemas.
 
 A live playground is available at **https://cbor.tech/cbor/**.
 
-This package exposes the `CBOR` facade plus a separate AST entrypoint for the
-CBOR node classes needed by extensions. Lower-level parser and encoder internals
+![Relationship between CBOR, CDN, and JavaScript values](./assets/cbor-cdn-js.png)
+
+This package exposes the CBOR facade plus separate CDN, CDDL, and AST
+entrypoints for tooling and extensions. Lower-level parser and encoder internals
 are not part of the documented public API.
 
 ## Install
@@ -75,6 +76,21 @@ console.log(value);
 // { hello: 'world', n: 42 }
 ```
 
+### Validate with CDDL
+
+Compile a CDDL schema and validate CBOR bytes, CDN text, or a `CborItem` AST
+against it:
+
+```ts
+import { CDDL } from '@cbortech/cbor/cddl';
+
+const schema = CDDL.compile('point = { x: int, y: int }');
+const result = schema.validate('{"x": 12, "y": -3}');
+
+console.log(result.valid);
+// true
+```
+
 ### CBOR Sequence to JavaScript values
 
 `decodeSeq` reads concatenated CBOR items as a CBOR Sequence and yields each item as a JavaScript value.
@@ -320,6 +336,45 @@ CBOR.format('`\\d+`', { preserveRawString: true });
 // '`\\d+`'
 ```
 
+### Preserve double-quoted string spelling
+
+By default, `CBOR.format()` re-escapes double-quoted text strings from their
+decoded value, so e.g. a `\uXXXX` escape becomes the literal character.
+`preserveTextString` re-emits a non-concatenated `"..."` literal using its
+original source spelling instead. (Raw backtick literals such as `` `...` ``
+are covered by `preserveRawString`, not this option; a string reached via
+`+` concatenation is normalised as usual regardless of this option.)
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+CBOR.format('"caf\\u00e9"');
+// '"café"'
+
+CBOR.format('"caf\\u00e9"', { preserveTextString: true });
+// '"caf\\u00e9"'
+```
+
+### Preserve number literal spelling
+
+By default, `CBOR.format()` normalizes integer and floating-point literals:
+hex/octal/binary integers (`0xff`, `0o377`, `0b101`) become decimal, trailing
+zeros and redundant encoding-indicator suffixes (`1.50`, `1.5_1`) are
+dropped. `preserveNumberFormat` re-emits these literals using their original
+CDN source spelling instead, taking precedence over `intFormat` /
+`floatFormat`. It only affects literals parsed from CDN text — values built
+with `CBOR.from()` or decoded from CBOR bytes always use normal formatting.
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+CBOR.format('{"a": 0xff, "b": 1.50}');
+// '{"a":255,"b":1.5}'
+
+CBOR.format('{"a": 0xff, "b": 1.50}', { preserveNumberFormat: true });
+// '{"a":0xff,"b":1.50}'
+```
+
 ### Preserve `+` string concatenation
 
 Note: `+` string concatenation was removed in draft-26. This section is for
@@ -356,6 +411,110 @@ CBOR.format("h'68' + b64'aQ'", {
 //   b64'aQ'
 ```
 
+### Preserve application-string/-sequence notation
+
+Some built-in extensions (`dt`/`DT`, `ip`/`IP`) support `prefix'...'`
+(application string), `` prefix`...` `` (backtick application string),
+`prefix<<...>>` (application sequence), and a raw tag literal (`N(...)`)
+notation for the same value, and by default regenerate `prefix'...'` from
+the resolved value on every `CBOR.format()` call — so
+`` DT`1969-07-21T02:56:16Z` ``, `DT<<'1969-07-21T02:56:16Z'>>`, and even the
+raw tag form `1(1749772800)` all normalize to `DT'...'` notation, and a
+non-canonical `DT'...'` spelling (e.g. a `+00:00` offset instead of `Z`)
+gets rewritten too. `preserveAppSequence` keeps the original spelling
+instead — whichever form was used. It has no effect when
+`appStrings: false` is also set (raw tag notation is used either way
+regardless of the original spelling), or on values not parsed from one of
+these forms.
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+CBOR.format('1(1749772800)');
+// "DT'2025-06-13T00:00:00Z'"
+
+CBOR.format('1(1749772800)', { preserveAppSequence: true });
+// "1(1749772800)"
+
+CBOR.format("DT<<'1969-07-21T02:56:16Z'>>", { preserveAppSequence: true });
+// "DT<<'1969-07-21T02:56:16Z'>>"
+
+CBOR.format('DT`1969-07-21T02:56:16Z`', { preserveAppSequence: true });
+// "DT`1969-07-21T02:56:16Z`"
+```
+
+### Preserve blank lines
+
+By default, `CBOR.format()` drops blank lines between array/map entries (and
+`(_ ...)` chunks) when re-serializing. `preserveBlankLines` re-emits a single
+blank line above an entry that had one anywhere before it in the source, so
+paragraph-like groupings of entries survive a reformat — at most one blank
+line per gap, regardless of how many were originally there. Detection is
+based on entry positions alone: it does not require `preserveComments` and is
+unaffected by whether comments are emitted. Only effective when `indent`
+enables pretty-printing; a container with a preserved blank line is always
+rendered one entry per line, even under `inlineLeafContainers`. Included in
+`preserveAll`.
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+const src = `[
+  1,
+  2,
+
+  3
+]`;
+
+CBOR.format(src, { indent: 2 });
+// [
+//   1,
+//   2,
+//   3
+// ]
+
+CBOR.format(src, { indent: 2, preserveBlankLines: true });
+// [
+//   1,
+//   2,
+//
+//   3
+// ]
+```
+
+### Format with minimal changes
+
+`preserveAll` turns on every `preserve*` option at once, to reformat CDN
+text — e.g. when reformatting on save in an editor — touching only
+whitespace/indentation and leaving most literals' original spelling
+untouched (bignums are the one exception; see `preserveNumberFormat`
+above). An explicitly-set individual option (including `false`) still wins
+over `preserveAll`.
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+CBOR.format('{"a":0xff,"b":1.5_1,"c":b64\'aGk=\'}', {
+  indent: 2,
+  preserveAll: true,
+});
+// {
+//   "a": 0xff,
+//   "b": 1.5_1,
+//   "c": b64'aGk='
+// }
+```
+
+`CBOR.format()` passes the same options to both `fromCDN()` and `toCDN()`
+internally, so this one option is enough. Calling them separately needs
+`preserveAll` (or `preserveComments`) on the `fromCDN()` side too, since
+comments must be captured while parsing to be re-emittable later:
+
+```ts
+const item = CBOR.fromCDN(text, { preserveAll: true });
+item.toCDN({ preserveAll: true, indent: 2 });
+```
+
 ### Validate CBOR / CDN / hex dump
 
 `validate` checks input for well-formedness and validity without throwing.
@@ -874,12 +1033,63 @@ Syntax errors thrown by `fromCDN`/`parse`/`tokenize` are `CdnSyntaxError`
 instances (a `SyntaxError` subclass, also exported from the main entry) and
 carry `offset`, `line`, `column`, and — where known — `endOffset`.
 
+## CDDL
+
+The `@cbortech/cbor/cddl` subpath contains a parser, compiler, and validator for
+CDDL, the schema language for describing CBOR data structures. A compiled schema
+validates CBOR bytes, CDN text, or a `CborItem` AST:
+
+```ts
+import { CDDL } from '@cbortech/cbor/cddl';
+
+const schema = CDDL.compile('point = { x: int, y: int }');
+
+console.log(schema.validate('{"x": 12, "y": -3}').valid);
+// true
+```
+
+Validation returns a result object rather than throwing. Failures include the
+instance path and source offsets for both the input and schema. Validation uses
+the first rule by default; pass `rule` to select another non-generic type rule.
+Options also include `features`, `maxDepth`, and `maxSteps`.
+
+All control operators from
+[RFC 8610](https://www.rfc-editor.org/rfc/rfc8610) are implemented, along with
+[RFC 9165](https://www.rfc-editor.org/rfc/rfc9165)'s `.plus`, `.cat`, and
+`.feature`. Enable `.feature` names with the `features` validation option.
+Unsupported operators such as `.abnf` are reported in `result.warnings` and
+matched without their constraint.
+
+The main `CBOR` facade also accepts a compiled schema or CDDL source text through
+the `cddl` option:
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+const value = CBOR.parse('{"x": 12, "y": -3}', {
+  cddl: 'point = { x: int, y: int }',
+});
+// { x: 12, y: -3 }
+```
+
+Throwing methods such as `parse`, `decode`, and `encode` throw
+`CddlMismatchError` on a mismatch; `CBOR.validate()` instead collects failures
+in `result.cddlErrors`. Pass validator options through `cddlValidationOptions`,
+or set `cddl` as an instance default with `new CBOR({ cddl: … })`.
+
+`CDDL.compile()` throws `CddlSyntaxError` or `CddlSemanticError`; use
+`{ strict: false }` to collect semantic issues in `schema.warnings` instead.
+Compiled schemas can be formatted with `schema.format()`. The subpath also
+exports `tokenize`, `tokenizeLenient`, and a typed rule AST through `schema.ast`
+and `schema.rules`.
+
 ## Public API
 
 The documented public exports are:
 
 - `CBOR`
 - `CdnSyntaxError`
+- `CddlMismatchError` (thrown by the `cddl` option; see [CDDL](#cddl))
 
 The `CBOR` facade also exposes:
 
@@ -893,41 +1103,35 @@ Lower-level CDN tokenization lives in `@cbortech/cbor/cdn`
 (`tokenize`, `tokenizeLenient`, `Token`, `TokenType`, `EdnComment`),
 and AST node classes in `@cbortech/cbor/ast`.
 
-## Specifications
-
-This library targets:
-
-- [CBOR, RFC 8949](https://www.rfc-editor.org/rfc/rfc8949)
-- [Concise Diagnostic Notation (CDN), draft-ietf-cbor-edn-literals-25](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/25/)
+The CDDL compiler lives in `@cbortech/cbor/cddl`
+(`CDDL`, `CddlSchema`, `CddlSyntaxError`, `CddlSemanticError`,
+`CddlMismatchError`, `tokenize`, `tokenizeLenient`, and the CDDL AST
+types).
 
-On top of draft -25, this library already incorporates parts of
-[draft -26](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/26/):
-
-- the `t1` / `b1` string-concatenation extensions (§3.4)
-- the `ilbs` / `ilts` indefinite-length string extensions (§3.5)
-- the `float` extension as a default extension (§3.7)
-- the draft-26 raw-string delimiter and trimming rules (§2.5.4): the closing
-  delimiter must have exactly as many backquotes as the opening one, and the
-  space-trimming rule applies to all delimiter lengths
-
-The legacy `+` string-concatenation syntax (removed in draft -26) and the
-`(_ ...)` streamstring syntax (deprecated in draft -26) are still accepted.
-Note that the CDN specification is still an Internet-Draft and may continue
-to change (for example, the extension names `t1` and `b1` are explicitly
-provisional).
-
-CDN is a human-readable text notation for CBOR data. It is useful for
-examples, test vectors, debugging, fixtures, and configuration-like files where
-raw CBOR bytes would be hard to read.
-
-It looks similar to JSON for ordinary arrays, maps, strings, numbers, booleans,
-and null values, but it can also represent CBOR-specific features such as byte
-strings, tags, simple values, indefinite-length items, non-string map keys, and
-application literals like `dt'2026-05-06T00:00:00Z'`.
+## Specifications
 
-CDN is a superset of JSON and JSONC, so ordinary JSON data and
-commented JSON-style data can be parsed and formatted as CDN without
-special handling.
+- CBOR
+  - [RFC 8949](https://www.rfc-editor.org/rfc/rfc8949)
+- CDN (CBOR-EDN)
+  - [draft-ietf-cbor-edn-literals-25](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/25/)
+  - [draft-ietf-cbor-edn-literals-26](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/26/)
+- CDDL
+  - [RFC 8610](https://www.rfc-editor.org/rfc/rfc8610)
+  - [RFC 9682](https://www.rfc-editor.org/rfc/rfc9682)
+  - [RFC 9165](https://www.rfc-editor.org/rfc/rfc9165)
+
+Implementation notes:
+
+- CDN follows draft-26 while retaining draft-25's `(_ ...)` streamstring syntax
+  and `+` string-concatenation syntax.
+- CDDL implements every RFC 8610 control operator, plus RFC 9165's `.plus`,
+  `.cat`, and `.feature`.
+- The RFC 9682 updates are implemented: its string-literal grammar (including
+  `\u{...}`), empty data models at the syntax layer (a model with no rules is
+  still a semantic error when compiled), and non-literal `#6.<type>` /
+  `#7.<type>` head numbers. Comment `PCHAR` validation, bare CR line endings,
+  and comments ending at EOF are intentionally accepted more leniently than the
+  collected ABNF.
 
 ## License