Specification & Definition
ADP’s tools are specified once and then used many times. This page introduces the words for that, and the languages it happens in. The source of these definitions is docs/terminology.md in etalii.adp; the Terminology page has the full vocabulary.
The concepts
Section titled “The concepts”- Tool: one of the new ways ADP offers to visualize, enter and interact with data, mostly text-based.
- Kind: every tool is of exactly one of three kinds. A diagram is a visual arrangement of elements and the relations between them; a designer is a form-based visual layout in which nothing is connected; an editor is a way of working in which typing text is the core interaction.
- Tool type: one particular tool ADP offers, such as the Wardley map; by kind a diagram type, designer type or editor type. It is identified by its origin,
<vendor>/<type>, for examplewardley/map. - Tool engineer: the person who specifies a tool type.
- Specification language: the language in which a tool engineer specifies how one tool type functions and looks. A specification file (
.dis,.des,.eds) holds one tool type: for example, what a state machine diagram’s elements and relations are and how they are drawn. - Definition language: the language in which the tools users create of a type are stored. A definition file (
.did,.ded,.edd) holds one diagram, designer or editor a user created of such a type: for example, one particular state machine.
The languages
Section titled “The languages”There is one specification language and one definition language per kind:
| Kind | Specification language | Extension | Definition language | Extension |
|---|---|---|---|---|
| Diagram | DISL, Diagram Specification Language | .dis |
DID, Diagram Definition Language | .did |
| Designer | DESL, Designer Specification Language | .des |
DED, Designer Definition Language | .ded, or a format the designer type's bindings read, such as .md |
| Editor | EDSL, Editor Specification Language | .eds |
EDD, Editor Definition Language | .edd |
DISL, DID, DESL and DED have content: follow their names to their references. DISL at a glance shows DISL’s main concepts and how they group together. EDSL and EDD are placeholders, with their content to come when an editor needs them. DID here always means ADP’s Diagram Definition Language, not the W3C’s Decentralized Identifiers.
Beside the six, the FBL, Format Binding Language (.fbl) serves every kind. When a tool’s model lives in another tool’s file, such as a Structurizr DSL workspace, a YAML file or a .mm mind map, an FBL document declares how the tool reads that file and writes its changes back while leaving every byte it did not change as it was. It also defines the .adp registration beside such a file, which names its tool type and keeps the positions a user placed, so they never have to be written into the file.
The ATD, ADP Tool Language (.atd) serves every kind too. A tool type of any kind is described in it completely, in one tool description written as text under one grammar. For now the tool descriptions are written and checked beside the JSON files, which every host still runs.