Specifications
The Specification tab gives you a complete view of everything known about a model item — its properties, narrative, diagrams, and all the related items that sit around it in the architecture.
To open a specification, navigate to any model item and click the Specification tab.
Page Layout
The specification page has three parts:
- Header — the item’s name, type label, status badge, and current version number.
- Contents sidebar — a sticky navigation panel on the left that links to each section. Only sections that contain data are shown.
- Main content area — the full specification, scrolling from top to bottom.
The sidebar is hidden on small screens and shown on medium and larger viewports.
Sections
The specification is divided into named section groups. Only groups that have at least one visible section are shown.
| Group | What it contains |
|---|---|
| Details | The item’s full narrative — rich text, diagrams, embedded images, and Draw.io diagrams. |
| Project Management | Release transitions, open issues, resolved issues, risks, building block dependencies, and associated tasks. |
| Business Context | Business outcomes, use cases, business scenarios, business processes, business rules, business information, organisational units, business roles, application roles, concepts, FAQs, and feature requests. |
| Requirements | Assumptions, design decisions, business requirements, non-functional requirements, transition requirements, acceptance criteria, implementation acceptance criteria, external references, and business references. |
| Assembly | Systems, applications, application patterns, UI components, reports, APIs, streams, services, data flows, data stores, technologies, and infrastructure environments. |
| Data | Data sets, data mappings, and test data. |
| Operations | Observability, availability, scalability, recoverability, performance, security, environments, and deployment mechanisms. |
Each section within a group shows only the relationships and content that are relevant to this specific item. If a section has nothing to show, it is omitted from both the sidebar and the main content.
The Project Management group is hidden when printing or exporting to PDF. All other groups are included in print output.
Display Options
Click the Display Options gear button (below the item header) to control what is shown on the page.
You can toggle:
- Narratives — show or hide the rich text narrative content within sections.
- Diagrams — show or hide PlantUML and embedded diagrams.
- Each section group individually — for example, hide the Operations group entirely if it is not relevant to your current review.
These display preferences are stored in the page URL, so you can share a link and the recipient will see the same filtered view.
Edit Mode
Project Editors and Admins can switch to Edit Mode using the floating button in the bottom-right corner of the page.
- In View Mode (mint button with a pencil icon), content is read-only.
- In Edit Mode (blue button with an eye icon), editable sections show inline editing controls.
The Edit Mode button is only visible to users with an Editor or Admin role on the project. Viewers always see the read-only view.
Click the button again to return to View Mode.
Downloading the Specification
Click Download Spec at the top-right of the specification page to download the full specification as a Markdown file.
The downloaded file includes the item’s properties, narrative, and all relationship sections — the same content shown on screen. This file is useful for sharing with stakeholders or attaching to external documents.
The download is available to all project members, including Viewers.
This is useful if you want to store a specification, such as for a UI Component, in the code repo alongside the code for the UI Component.
Baselines
You can capture a point-in-time snapshot of the specification using a Specification Baseline. Baselines record the exact state of the item — properties, narrative, diagrams, and the versions of all dependencies — so you can compare them against the current state later.
See Baselines for full details on creating, viewing, and using baselines.