Choosing Element Types

A step-by-step heuristic for selecting from the element types, organized by domain - what to reach for and when.

Element types are a vocabulary, not a prescription. There are more than seventy of them across four domains — AI/ML, Business, Product, and Software — plus the Workflow (BPMN) control-flow types and hundreds more for cloud and open-source infrastructure, and every one carries a name, a description, and typed fields. A diagram that names its concepts precisely gives the AI more to work with, so the craft is choosing the right type per node and filling it honestly.

The categories at a glance

The Domains view of the Types overlay holds the free core vocabulary:

• AI/ML — how the AI thinks and acts: Agent, Context, Dataset, Evaluation, Guardrail, Human, Knowledge, Markdown, MCP Server, Memory, Model, Output, Prompt, Router, Rule, Session, Skill, Tool
• Business — strategy and governance: Assumption, Budget, Competitor, Constraint, Customer, Decision, Dependency, Initiative, Key Result, KPI, Milestone, Objective, Partner, Policy, Question, Requirement, Risk, Stakeholder
• Product — users, discovery, and delivery: Criteria, Epic, Experiment, Feature, Feedback, Hypothesis, Insight, Journey, Metric, Outcome, Persona, Problem, Release, Roadmap, Story, To-do
• Software — technical architecture: Client, Component, Config, Database, Decision, Dependency, Endpoint, Environment, Event, Feature Flag, Interface, Issue, Job, Model, Pipeline, Queue, Repository, Service, System, Test
• Workflow (BPMN) — process plumbing: start events, end events, gateways, tasks, annotations, and data stores — see Flow & Structure Elements

Two further views cover infrastructure: Cloud (Generic, AWS, Azure, Google Cloud, Cloudflare) and Open Source (hundreds of self-hostable projects). They’re one-time add-ons — see Cloud & Open Source Types.

Each category page in the Reference documents every type’s fields and exact meaning.

A process for choosing

1. Ask what the node is, not what it does. A node that states a constraint is a Rule. A node that names a capability with concrete implementation is a Tool. A node that gives the AI background knowledge is a Context. Match the concept first, then fill in that type’s attributes.
2. If two types fit, pick the more specific one — and read the descriptions. Many types come in deliberate pairs: a KPI tracks an initiative while a Key Result measures one Objective; a Hypothesis is tested while an Assumption is taken as true; Feedback is the raw input while an Insight is the conclusion; an Event is the message contract while a Queue is the channel; a Business Decision differs from a Software Decision (an ADR); a Software Model is a data schema while an AI/ML Model is an LLM. Hover a tile in the Types overlay to read its description. When you care about the distinction downstream, so does your AI. When you genuinely don’t, the generic Task (untyped) is always honest — its name and description still say what it means.
3. Borrow from every category in the same diagram. The categories don’t have to agree; a real slice of work usually spans them. The CSV-export example combines a Persona, Story, Requirement, Endpoint, Test, and Issue — three categories, one coherent feature. Don’t build “an AI diagram” or “a product diagram”; build this problem’s diagram.
4. Change your mind cheaply. Select one or more elements and press T (or click ⇋ in the action menu or the Properties panel header) to switch type when a better fit appears. The name, description, and any fields the new type shares come along; fields it doesn’t have are cleared, and one undo restores everything. Type choice is a refactoring, not a commitment.

Say what the type means — in your diagram

Because types are a vocabulary, each has an intentionally general description in the type catalog — a story might mean a user story here and a blog post there. The Library panel lists every type in use in your diagram with its description; edit those descriptions, and they’re written into the file’s type dictionary, which travels with every save, Copy XML, and raw link — the AI reading the file sees what each type means in this context.

Heuristics worth internalizing

• Name with nouns, describe with intent. “Price Rule”, not “This rule is about price”; one-liners in the name, nuance in the description (dai:notes).
• Scope what should be scoped. Global rules and context apply to everything; local ones only flow downstream through connections — placement is meaningful.
• Connect before you over-describe. A connected pair with modest text often beats four lonely nodes with paragraphs, because connections establish what relates to what (see Structuring with Nested Groups).
• When in doubt, describe it the way you’d brief a new teammate. If a node needs a paragraph to explain, that paragraph belongs in its description, not left implicit — the Properties panel’s ⇤ expand mode gives you room to write it.

The full type catalogue, with every field and example, is the Element Types reference.