Joseph Potvin wrote in #note-1:
Apologies that I didn't point to this explicitly & also put it into a README:
https://gitlab.com/xalgorithms-alliance/data-with-direction-specification/dwds-documents/-/blob/16918d90c276397a23e9c83bf59e5bac043cd81b/current/Refinement%20of%20the%20DWD%20Data%20Structure.pdf
Excuse: My instinct was to get some feedback first, but evidently I forgot to ask. (The ODT is attached here for editing if you prefer.)
Thanks I'll certainly use that reference, this is a good resource to explain the design of the data format.
But my meaning of a technical specification is one oriented for programmers to implement the format, not just understand its goal and design decisions.
The concern of that technical specification is precise guidelines and prescriptions for an implementation to parse or generate the format, in order to guarantee interoperability of any implementation following the specification.
The concerns being technical details, in technical terms, I would keep it separate from the design motivations (they can reference each other though).
Note that the same design motivations can allow for multiple technical specifications, where specific technical concerns discovered in implementation and usage may lead to iteration of the technical specification without overriding the original design decisions.
Example technical specifications:
The important aspects:
- how the different datatypes are encoded
- the specific character sequences (with ASCII / UTF-8 encodings) to expect in the structure
- specific constraints (e.g. field lengths) that should be accounted for in parser or generator implementations
- practical recommendations for implementors (e.g. for performance, or correctness / robustness)
- a standard-form grammar (usually ABNF )
Attached is a WIP specification. The source is in markdown (.md), a text-based markup language. txt and html formats are generated from it (I used IETF RFC tooling). I had coding agents generate most of it from example files and those documents of yours. Many points I'm pretty sure we want to change or needing discussion, but that suggests the kind of information we need to coordinate implementations.
-