From an interface document to a dictionary
An interface control document (ICD) defines the messages two systems exchange, usually as hundreds of pages of word-and-bit tables. A first-bite dictionary holds the same definitions as JSON the decoder loads. This guide is the way from one to the other: what to read out of the document, the conventions that make two people's transcriptions come out the same, the bite commands that catch mistakes, and how to keep the dictionary right when the document is revised.
The path
Step What you do Command Page 1. Scope Fix the document, its revision and the interfaces to transcribe. Read its distribution statement; the dictionary inherits it. Start the repository. bite new <dir> --repoconventions 2. Inventory List every interface and every message the document names, with its identifier, whether or not you will define it. messages.csvreading an ICD 3. Numbering Establish the word size, which end of a word is bit 0, and whether words count from 0 or 1. Test it on a field whose value you know. bite rangereading an ICD 4. Transcribe Enter one row per field, with the word and bits exactly as printed. bite import-csvworkflow 5. Check Run the four gates until they pass. bite fmt, bite check --strict, bite lint, bite coverage --strictworkflow 6. Vectors Turn the document's example messages into test vectors, one per message at least. bite vectors new, bite vectors encodevectors 7. Review A second person reads every field against the document. pull request checklists 8. Version Give the dictionary a version the changes justify. bite diff --check-versionconventions 9. Maintain When the document is revised, transcribe the changes and compare. bite diffmaintaining
The worked example goes through all nine on a synthetic 12-page document, and retrace.sh runs it end to end and compares the result with dictionaries/glasshouse byte for byte.
Pages
Page Covers 01 Reading an ICD what to extract and where documents put it; bit numbering with worked conversions; signed encodings; scaling; enumerations; what the format cannot express 02 Conventions names, units, labels, descriptions, sources, versions, repository layout, handling; every bite lint and bite coverage rule 03 Transcription workflow the working loop; the four CSV tables column by column; errata and ambiguities 04 Vectors and validation where expected values come from; building payloads; what a capture can and cannot tell you 05 Maintaining a new revision of the document; bite diff; deprecation; the changelog 06 Worked example a synthetic document, its tables, the dictionary and the output of every step Checklists transcription, review, release
What catches what
Mistake Caught by The same definition written two ways; a field name used twice in a message bite fmt --checkA bit range with stop before start; a field wider than its type allows bite check (error)Two fields sharing bits; a message named and not defined bite check --strictBits that belong to no field; a field past the message's stated length bite coverage --strictA field with no source, description or unit; a message with no vector bite coverage --strictA name, unit or label off the conventions; a label on a reserved value bite lintThe word and bits typed for a field disagreeing with its start and stop bite import-csvA field at the wrong bits, or with the wrong scale, sign or byte order a vector from the document's examples, run by bite check A payload in the document that the field values do not account for bite vectors encode --vectorA value copied wrong that still decodes to something plausible the second reader A field that never changes, or values outside an enumeration, in real traffic bite statsA change that breaks consumers, released as a minor version bite diff --check-version
Status
Part Status bite new, range, import-csv, export-csv, fmt, coverage, lint, diff, vectors new, vectors encode, statsbuilt; tests in bite/tests/authoring.rs and bite/tests/cli.rs Worked example measured: retrace.out is the output of retrace.sh Repository template, tools/dictionary-repo-template built; its workflow has not run on GitHub, because no first-bite release carries these commands yet PDF table extraction, tools/icd-extract built for tables laid out like the worked example's; measured on its PDF Repeated groups, conditional layouts, sign-magnitude and BCD fields in the dictionary format not built; what to do meanwhile
The source of this page is a Markdown file in the repository .