cddl-verifier 0.1.0__tar.gz

cddl_verifier-0.1.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
+project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The version is defined once in `src/cddl_verifier/_version.py`. 0.1.0 is the first
+public release ([#84](https://github.com/sahebbiswas/cddl_verifier/issues/84)); the section below gets its date when the release is published.
+
+## [Unreleased] - 0.1.0
+
+### Changed
+- **Breaking:** the code is now the `cddl_verifier` package (source under
+  `src/cddl_verifier/`). The top-level modules `simple_cbor`, `cbor_json`,
+  `cbor_cddl_analyzer` and `_version` are no longer installed; their code lives
+  in the internal modules `cddl_verifier._cbor`, `._json_codec`, `._analyzer`
+  and `._version`. Use the public API below instead.
+- `cddl-verify` now points at `cddl_verifier.cli:main`; `python -m cddl_verifier`
+  runs the same CLI. The CBOR/JSON converter runs as
+  `python -m cddl_verifier.json_codec`.
+- Using the library no longer prints log messages: the package logger
+  (`cddl_verifier`) has only a `NullHandler`, and the CLI attaches its coloured
+  stderr handler while it runs.
+- Package metadata: `requires-python = ">=3.9"`, classifiers, SPDX `MIT`
+  license, project URLs, `test` and `dev` extras. The unused `cbor2` extra was
+  removed; there are no runtime dependencies.
+- **Behaviour change** from earlier unversioned code: `CBOR.load()`, `CBOR.loads()`, `cbor_decode()` and
+  `load_cbor_bytes()` now decode exactly one complete CBOR data item. Trailing
+  bytes after the item (including concatenated CBOR sequences), which were
+  previously ignored silently, are rejected with `CBORTrailingDataError`
+  ([#64](https://github.com/sahebbiswas/cddl_verifier/issues/64)). The analyzer CLI and nested `.cbor` validation inherit this behaviour.
+- Decoder errors are now `CBORDecodeError` (a `ValueError` subclass) carrying the
+  byte `offset` of the problem: `CBORTruncatedError` for empty or truncated
+  input, `CBORTrailingDataError` for trailing bytes, `CBORUnsupportedError`
+  (also a `NotImplementedError`) for indefinite-length items and `undefined`.
+  Invalid UTF-8, reserved additional-info values, duplicate map keys and
+  excessive nesting also raise `CBORDecodeError` instead of leaking
+  `UnicodeDecodeError` / `RecursionError`.
+- Decoding accepts `bytearray` and `memoryview`; non-bytes input raises
+  `TypeError`.
+
+### Fixed
+- Validating against a root rule that is a plain primitive (`n = uint`) now
+  checks the value instead of always failing with "not a concrete type".
+- A tagged root rule (`root = #6.501(inner)`) now requires the data to carry
+  that tag number; data with a different tag, or no tag, was accepted before.
+
+### Added
+- Public API ([#84](https://github.com/sahebbiswas/cddl_verifier/issues/84)):
+  `cddl_verifier.validate()`, `Validator` (with `to_edn()`), `ValidationResult`,
+  `Diagnostic` and `SchemaError`. Undecodable CBOR is reported as a `"decode"`
+  diagnostic with a byte offset instead of being raised.
+- `cddl_verifier.cbor` (`encode`, `decode`, `diag_dump`, `CBOR`, decode errors)
+  and `cddl_verifier.json_codec` as the public CBOR and JSON helpers.
+- `tests/test_public_api.py` for the public API and `python -m cddl_verifier`.
+- CI builds the wheel and sdist, runs `twine check`, and runs the test suite
+  against the installed wheel on Python 3.9–3.13 and the sdist on 3.11.
+- `MANIFEST.in`, so the sdist includes the tests, test data and docs.
+- README: installation from PyPI, quick start, supported features, known
+  limitations (`.size` [#67](https://github.com/sahebbiswas/cddl_verifier/issues/67),
+  canonical floats [#66](https://github.com/sahebbiswas/cddl_verifier/issues/66)) and release steps.
+- Versioning scheme: `_version.py` as the single version source, this
+  changelog, `[project]` metadata in `pyproject.toml`, and a `--version` flag.
+- `.github/workflows/publish_pypi.yml`: builds the sdist and wheel, runs
+  `twine check`, smoke-tests both artifacts in clean environments, and
+  publishes with PyPI Trusted Publishing: to TestPyPI on manual runs, and to
+  TestPyPI then PyPI when a GitHub release is published (the only path to PyPI)
+  ([#84](https://github.com/sahebbiswas/cddl_verifier/issues/84)).
+- `pip install .` installs a `cddl-verify` console script.
+- `docs/CLI.md`, `docs/API.md` and `docs/CDDL_SUPPORT.md` reference pages; the
+  README is now a short overview that links to them. EDN and diagnostic-dump
+  samples were regenerated from real output.
+- `tests/test_strict_decoding.py`: regression tests for scalars, maps, arrays,
+  tags and nested data with trailing bytes, truncation at every prefix, and
+  error offsets.
+
+### Removed
+- `fix_indent_proper.py`, a one-off script that edited `cbor_cddl_analyzer.py`
+  in place and no longer applies to the package layout.

cddl_verifier-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saheb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cddl_verifier-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+# Extra files for the sdist, so it can be tested on its own.
+include CHANGELOG.md TESTING.md requirements.txt
+recursive-include docs *.md
+recursive-include tests *.py
+recursive-include cddl-schemas *.cddl *.edn
+recursive-include test-data *.cbor

cddl_verifier-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: cddl-verifier
+Version: 0.1.0
+Summary: Validate CBOR data against CDDL schemas, generate annotated EDN, and convert CBOR/JSON
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sahebbiswas/cddl_verifier
+Project-URL: Source, https://github.com/sahebbiswas/cddl_verifier
+Project-URL: Issues, https://github.com/sahebbiswas/cddl_verifier/issues
+Project-URL: Changelog, https://github.com/sahebbiswas/cddl_verifier/blob/main/CHANGELOG.md
+Keywords: cbor,cddl,edn,rfc8610,rfc8949,corim,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+[![Python CI](https://github.com/sahebbiswas/cddl_verifier/actions/workflows/ci.yml/badge.svg)](https://github.com/sahebbiswas/cddl_verifier/actions/workflows/ci.yml)
+
+# cddl-verifier
+
+Validate CBOR (RFC 8949) data against CDDL (RFC 8610) schemas, render it as
+annotated EDN (Extended Diagnostic Notation), and convert between CBOR and JSON.
+It is built for attestation formats such as CoRIM and CoSWID.
+
+> **Scope.** cddl-verifier supports a practical subset of CDDL and CBOR. It does
+> **not** claim full RFC 8610 or RFC 8949 conformance yet; see
+> [Limitations](#limitations) and [docs/CDDL_SUPPORT.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CDDL_SUPPORT.md).
+
+| Surface | Name |
+|---------|------|
+| PyPI distribution | `cddl-verifier` |
+| Python import package | `cddl_verifier` |
+| Command-line tool | `cddl-verify` |
+
+## Installation
+
+```bash
+pip install cddl-verifier
+```
+
+Requires Python 3.9 or newer. There are no runtime dependencies: CBOR encoding
+and decoding are bundled. Extras for contributors: `pip install "cddl-verifier[test]"`
+(pytest) and `[dev]` (pytest, build, twine).
+
+## Quick start
+
+### Command line
+
+```bash
+cddl-verify schema.cddl data.cbor --type corim-map                     # validate, print annotated EDN
+cddl-verify schema.cddl data.cbor --type corim-map --output data.edn   # write EDN to a file
+cddl-verify schema.cddl data.cbor --show-types                         # list the parsed CDDL types
+```
+
+The exit status is `1` when the CBOR cannot be decoded or, with `--type`, when
+validation fails. Without `--type` the first rule is used and validation errors
+are only warnings (exit status `0`).
+`python -m cddl_verifier` takes the same arguments. See [docs/CLI.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CLI.md).
+
+### Python
+
+```python
+from pathlib import Path
+from cddl_verifier import validate
+
+result = validate(Path("schema.cddl"), Path("data.cbor").read_bytes(),
+                  root_type="corim-map")
+if result.valid:
+    print("valid")
+else:
+    for diagnostic in result.diagnostics:
+        print(diagnostic.code, diagnostic.message)
+```
+
+- `schema` is CDDL text (`str`) or a path (`pathlib.Path`).
+- `data` is CBOR bytes or an already-decoded Python value.
+- `root_type` defaults to the first rule in the schema.
+- CBOR that cannot be decoded gives an invalid result with a `"decode"`
+  diagnostic and its byte offset; it does not raise.
+
+To check many items against one schema, or to render EDN, use `Validator`:
+
+```python
+from cddl_verifier import Validator
+
+validator = Validator(Path("schema.cddl"))
+result = validator.validate(cbor_bytes, root_type="corim-map")
+print(validator.to_edn(cbor_bytes, root_type="corim-map"))
+```
+
+CBOR and JSON helpers:
+
+```python
+from cddl_verifier.cbor import encode, decode
+from cddl_verifier.json_codec import cbor_to_json
+
+raw = encode({0: "Alice", 1: b"\x01"}, canonical=True)
+assert decode(raw) == {0: "Alice", 1: b"\x01"}
+print(cbor_to_json(raw, typed=True, pretty=True))
+```
+
+Decoding is strict: the input must be exactly one complete CBOR item. Empty,
+truncated or trailing-byte input raises `CBORDecodeError` with the byte offset
+of the problem. See [docs/API.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/API.md) for the full API.
+
+## What is supported
+
+- CDDL maps, arrays, type aliases, groups, type choices (`/=`), sockets (`//=`),
+  optional fields, occurrence indicators, IANA-registered parameters
+  (`&(name: n)`), CBOR tags (`#6.n(...)`), `.cbor`, `.size`, `.regexp` and
+  value-range controls on integers. Details: [docs/CDDL_SUPPORT.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CDDL_SUPPORT.md).
+- Real CoRIM and CoSWID schemas: [docs/CORIM_SUPPORT.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CORIM_SUPPORT.md).
+- CBOR encoding and strict decoding with byte offsets in errors; duplicate map
+  keys, invalid UTF-8 and excessive nesting are rejected.
+- Annotated EDN output with field names from the schema.
+- CBOR ↔ JSON conversion. `typed=True` keeps byte strings and tags, but
+  non-string map keys (such as the integer keys in CoRIM maps) still become JSON
+  strings, so maps with such keys do not round-trip exactly.
+
+## Limitations
+
+- **CDDL**: a practical subset, not the full RFC 8610 grammar. Malformed schemas
+  are often accepted without an error. A standards-oriented parser is planned
+  ([#69](https://github.com/sahebbiswas/cddl_verifier/issues/69),
+  [#70](https://github.com/sahebbiswas/cddl_verifier/issues/70)).
+- **`.size`**: counts characters instead of UTF-8 bytes on `tstr`, and is not
+  enforced on `uint` ([#67](https://github.com/sahebbiswas/cddl_verifier/issues/67)).
+- **Canonical encoding**: map keys are sorted and integers are shortest-form,
+  but floats are always written as 8-byte doubles, so output is not fully RFC 8949
+  §4.2 deterministic ([#66](https://github.com/sahebbiswas/cddl_verifier/issues/66)).
+- **CBOR**: indefinite-length items and `undefined` are not supported
+  (`CBORUnsupportedError`). CBOR sequences are rejected; a sequence API is not
+  available yet.
+- **Value types**: tags decode to `(tag, value)` tuples and arrays or maps used
+  as map keys decode to tuples. These are provisional and expected to change
+  ([#78](https://github.com/sahebbiswas/cddl_verifier/issues/78),
+  [#88](https://github.com/sahebbiswas/cddl_verifier/issues/88)).
+
+## Documentation
+
+| Document | Contents |
+|----------|----------|
+| [docs/CLI.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CLI.md) | `cddl-verify` and JSON converter options, input rules, EDN output formats |
+| [docs/API.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/API.md) | Python API: `validate`, `Validator`, CBOR and JSON helpers |
+| [docs/CDDL_SUPPORT.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CDDL_SUPPORT.md) | Supported CDDL syntax, types, and validation behaviour |
+| [docs/CORIM_SUPPORT.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CORIM_SUPPORT.md) | CoRIM / CoSWID schema support |
+| [docs/CBOR_BUILDER_QUICK_REF.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CBOR_BUILDER_QUICK_REF.md), [docs/ITERATIVE_CONSTRUCTION.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/ITERATIVE_CONSTRUCTION.md) | `CBOR` builder API in depth |
+| [docs/CBOR_DIAGNOSTIC_DUMP.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CBOR_DIAGNOSTIC_DUMP.md) | Diagnostic dump format |
+| [docs/CANONICAL_AND_JSON.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CANONICAL_AND_JSON.md) | Canonical encoding and JSON round-trips |
+| [docs/](https://github.com/sahebbiswas/cddl_verifier/tree/main/docs) | EDN formatting, tag notation, and annotation notes |
+| [TESTING.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/TESTING.md) | Running and writing tests, CI setup |
+| [CHANGELOG.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/CHANGELOG.md) | Release history |
+
+## Development
+
+```bash
+git clone https://github.com/sahebbiswas/cddl_verifier
+cd cddl_verifier
+pip install -e ".[test]"
+pytest
+```
+
+The package source is in `src/cddl_verifier/`. Modules whose names start with
+an underscore are internal. See [TESTING.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/TESTING.md).
+
+## Versioning
+
+The project follows [Semantic Versioning 2.0.0](https://semver.org/). While the
+major version is `0`, a minor bump (`0.x.0`) may contain breaking changes and a
+patch bump (`0.x.y`) is for backward-compatible fixes. The stable surface is the
+public API above (`cddl_verifier`, `cddl_verifier.cbor`,
+`cddl_verifier.json_codec`) and the `cddl-verify` CLI; underscore modules are not
+covered.
+
+- The version is defined once, as `__version__` in
+  [`src/cddl_verifier/_version.py`](https://github.com/sahebbiswas/cddl_verifier/blob/main/src/cddl_verifier/_version.py).
+  `pyproject.toml` reads it, `cddl_verifier.__version__` exposes it, and
+  `cddl-verify --version` prints it. Don't repeat the version number elsewhere.
+- A change that alters behaviour bumps the version and adds an entry to
+  [CHANGELOG.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/CHANGELOG.md) (format: [Keep a Changelog](https://keepachangelog.com/)).
+  Follow-up commits before a release go into the same, still-unreleased version.
+- Update this README and `docs/` in the same change as the code they describe.
+
+## Releasing
+
+Releases go to PyPI through [`publish_pypi.yml`](https://github.com/sahebbiswas/cddl_verifier/blob/main/.github/workflows/publish_pypi.yml),
+which uses PyPI Trusted Publishing (no API tokens are stored).
+
+1. Set the version in `_version.py`, date its CHANGELOG section, and merge to `main`.
+2. Optional dry run: start the workflow manually (Actions → *Publish to PyPI /
+   TestPyPI* → *Run workflow*); manual runs only upload to TestPyPI. A version can
+   only be uploaded once per index, so use a pre-release such as `0.1.1rc1` for
+   trial uploads. A release fails if its version is already on TestPyPI.
+3. Publish a GitHub release with tag `vX.Y.Z` matching the version. The workflow
+   builds and checks the distributions, tests the wheel and sdist, uploads to
+   TestPyPI, installs from there, and then uploads to PyPI.
+
+One-time setup: on pypi.org and test.pypi.org, add a (pending) trusted publisher
+for repository `sahebbiswas/cddl_verifier`, workflow `publish_pypi.yml`, and
+environment `pypi` / `testpypi` respectively (or "any" environment). GitHub
+creates the environments on first use; add a required reviewer to `pypi` to gate
+production uploads.

cddl_verifier-0.1.0/README.md

@@ -0,0 +1,186 @@
+[![Python CI](https://github.com/sahebbiswas/cddl_verifier/actions/workflows/ci.yml/badge.svg)](https://github.com/sahebbiswas/cddl_verifier/actions/workflows/ci.yml)
+
+# cddl-verifier
+
+Validate CBOR (RFC 8949) data against CDDL (RFC 8610) schemas, render it as
+annotated EDN (Extended Diagnostic Notation), and convert between CBOR and JSON.
+It is built for attestation formats such as CoRIM and CoSWID.
+
+> **Scope.** cddl-verifier supports a practical subset of CDDL and CBOR. It does
+> **not** claim full RFC 8610 or RFC 8949 conformance yet; see
+> [Limitations](#limitations) and [docs/CDDL_SUPPORT.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CDDL_SUPPORT.md).
+
+| Surface | Name |
+|---------|------|
+| PyPI distribution | `cddl-verifier` |
+| Python import package | `cddl_verifier` |
+| Command-line tool | `cddl-verify` |
+
+## Installation
+
+```bash
+pip install cddl-verifier
+```
+
+Requires Python 3.9 or newer. There are no runtime dependencies: CBOR encoding
+and decoding are bundled. Extras for contributors: `pip install "cddl-verifier[test]"`
+(pytest) and `[dev]` (pytest, build, twine).
+
+## Quick start
+
+### Command line
+
+```bash
+cddl-verify schema.cddl data.cbor --type corim-map                     # validate, print annotated EDN
+cddl-verify schema.cddl data.cbor --type corim-map --output data.edn   # write EDN to a file
+cddl-verify schema.cddl data.cbor --show-types                         # list the parsed CDDL types
+```
+
+The exit status is `1` when the CBOR cannot be decoded or, with `--type`, when
+validation fails. Without `--type` the first rule is used and validation errors
+are only warnings (exit status `0`).
+`python -m cddl_verifier` takes the same arguments. See [docs/CLI.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CLI.md).
+
+### Python
+
+```python
+from pathlib import Path
+from cddl_verifier import validate
+
+result = validate(Path("schema.cddl"), Path("data.cbor").read_bytes(),
+                  root_type="corim-map")
+if result.valid:
+    print("valid")
+else:
+    for diagnostic in result.diagnostics:
+        print(diagnostic.code, diagnostic.message)
+```
+
+- `schema` is CDDL text (`str`) or a path (`pathlib.Path`).
+- `data` is CBOR bytes or an already-decoded Python value.
+- `root_type` defaults to the first rule in the schema.
+- CBOR that cannot be decoded gives an invalid result with a `"decode"`
+  diagnostic and its byte offset; it does not raise.
+
+To check many items against one schema, or to render EDN, use `Validator`:
+
+```python
+from cddl_verifier import Validator
+
+validator = Validator(Path("schema.cddl"))
+result = validator.validate(cbor_bytes, root_type="corim-map")
+print(validator.to_edn(cbor_bytes, root_type="corim-map"))
+```
+
+CBOR and JSON helpers:
+
+```python
+from cddl_verifier.cbor import encode, decode
+from cddl_verifier.json_codec import cbor_to_json
+
+raw = encode({0: "Alice", 1: b"\x01"}, canonical=True)
+assert decode(raw) == {0: "Alice", 1: b"\x01"}
+print(cbor_to_json(raw, typed=True, pretty=True))
+```
+
+Decoding is strict: the input must be exactly one complete CBOR item. Empty,
+truncated or trailing-byte input raises `CBORDecodeError` with the byte offset
+of the problem. See [docs/API.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/API.md) for the full API.
+
+## What is supported
+
+- CDDL maps, arrays, type aliases, groups, type choices (`/=`), sockets (`//=`),
+  optional fields, occurrence indicators, IANA-registered parameters
+  (`&(name: n)`), CBOR tags (`#6.n(...)`), `.cbor`, `.size`, `.regexp` and
+  value-range controls on integers. Details: [docs/CDDL_SUPPORT.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CDDL_SUPPORT.md).
+- Real CoRIM and CoSWID schemas: [docs/CORIM_SUPPORT.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CORIM_SUPPORT.md).
+- CBOR encoding and strict decoding with byte offsets in errors; duplicate map
+  keys, invalid UTF-8 and excessive nesting are rejected.
+- Annotated EDN output with field names from the schema.
+- CBOR ↔ JSON conversion. `typed=True` keeps byte strings and tags, but
+  non-string map keys (such as the integer keys in CoRIM maps) still become JSON
+  strings, so maps with such keys do not round-trip exactly.
+
+## Limitations
+
+- **CDDL**: a practical subset, not the full RFC 8610 grammar. Malformed schemas
+  are often accepted without an error. A standards-oriented parser is planned
+  ([#69](https://github.com/sahebbiswas/cddl_verifier/issues/69),
+  [#70](https://github.com/sahebbiswas/cddl_verifier/issues/70)).
+- **`.size`**: counts characters instead of UTF-8 bytes on `tstr`, and is not
+  enforced on `uint` ([#67](https://github.com/sahebbiswas/cddl_verifier/issues/67)).
+- **Canonical encoding**: map keys are sorted and integers are shortest-form,
+  but floats are always written as 8-byte doubles, so output is not fully RFC 8949
+  §4.2 deterministic ([#66](https://github.com/sahebbiswas/cddl_verifier/issues/66)).
+- **CBOR**: indefinite-length items and `undefined` are not supported
+  (`CBORUnsupportedError`). CBOR sequences are rejected; a sequence API is not
+  available yet.
+- **Value types**: tags decode to `(tag, value)` tuples and arrays or maps used
+  as map keys decode to tuples. These are provisional and expected to change
+  ([#78](https://github.com/sahebbiswas/cddl_verifier/issues/78),
+  [#88](https://github.com/sahebbiswas/cddl_verifier/issues/88)).
+
+## Documentation
+
+| Document | Contents |
+|----------|----------|
+| [docs/CLI.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CLI.md) | `cddl-verify` and JSON converter options, input rules, EDN output formats |
+| [docs/API.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/API.md) | Python API: `validate`, `Validator`, CBOR and JSON helpers |
+| [docs/CDDL_SUPPORT.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CDDL_SUPPORT.md) | Supported CDDL syntax, types, and validation behaviour |
+| [docs/CORIM_SUPPORT.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CORIM_SUPPORT.md) | CoRIM / CoSWID schema support |
+| [docs/CBOR_BUILDER_QUICK_REF.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CBOR_BUILDER_QUICK_REF.md), [docs/ITERATIVE_CONSTRUCTION.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/ITERATIVE_CONSTRUCTION.md) | `CBOR` builder API in depth |
+| [docs/CBOR_DIAGNOSTIC_DUMP.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CBOR_DIAGNOSTIC_DUMP.md) | Diagnostic dump format |
+| [docs/CANONICAL_AND_JSON.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/docs/CANONICAL_AND_JSON.md) | Canonical encoding and JSON round-trips |
+| [docs/](https://github.com/sahebbiswas/cddl_verifier/tree/main/docs) | EDN formatting, tag notation, and annotation notes |
+| [TESTING.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/TESTING.md) | Running and writing tests, CI setup |
+| [CHANGELOG.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/CHANGELOG.md) | Release history |
+
+## Development
+
+```bash
+git clone https://github.com/sahebbiswas/cddl_verifier
+cd cddl_verifier
+pip install -e ".[test]"
+pytest
+```
+
+The package source is in `src/cddl_verifier/`. Modules whose names start with
+an underscore are internal. See [TESTING.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/TESTING.md).
+
+## Versioning
+
+The project follows [Semantic Versioning 2.0.0](https://semver.org/). While the
+major version is `0`, a minor bump (`0.x.0`) may contain breaking changes and a
+patch bump (`0.x.y`) is for backward-compatible fixes. The stable surface is the
+public API above (`cddl_verifier`, `cddl_verifier.cbor`,
+`cddl_verifier.json_codec`) and the `cddl-verify` CLI; underscore modules are not
+covered.
+
+- The version is defined once, as `__version__` in
+  [`src/cddl_verifier/_version.py`](https://github.com/sahebbiswas/cddl_verifier/blob/main/src/cddl_verifier/_version.py).
+  `pyproject.toml` reads it, `cddl_verifier.__version__` exposes it, and
+  `cddl-verify --version` prints it. Don't repeat the version number elsewhere.
+- A change that alters behaviour bumps the version and adds an entry to
+  [CHANGELOG.md](https://github.com/sahebbiswas/cddl_verifier/blob/main/CHANGELOG.md) (format: [Keep a Changelog](https://keepachangelog.com/)).
+  Follow-up commits before a release go into the same, still-unreleased version.
+- Update this README and `docs/` in the same change as the code they describe.
+
+## Releasing
+
+Releases go to PyPI through [`publish_pypi.yml`](https://github.com/sahebbiswas/cddl_verifier/blob/main/.github/workflows/publish_pypi.yml),
+which uses PyPI Trusted Publishing (no API tokens are stored).
+
+1. Set the version in `_version.py`, date its CHANGELOG section, and merge to `main`.
+2. Optional dry run: start the workflow manually (Actions → *Publish to PyPI /
+   TestPyPI* → *Run workflow*); manual runs only upload to TestPyPI. A version can
+   only be uploaded once per index, so use a pre-release such as `0.1.1rc1` for
+   trial uploads. A release fails if its version is already on TestPyPI.
+3. Publish a GitHub release with tag `vX.Y.Z` matching the version. The workflow
+   builds and checks the distributions, tests the wheel and sdist, uploads to
+   TestPyPI, installs from there, and then uploads to PyPI.
+
+One-time setup: on pypi.org and test.pypi.org, add a (pending) trusted publisher
+for repository `sahebbiswas/cddl_verifier`, workflow `publish_pypi.yml`, and
+environment `pypi` / `testpypi` respectively (or "any" environment). GitHub
+creates the environments on first use; add a required reviewer to `pypi` to gate
+production uploads.