navigation-specs Specification
Purpose
Navigation as data, the structure (what exists and how it is grouped, shared and validated alike by every client) kept apart from its representation (how each client draws it, a per-client profile). Rationale and prior art: the archived change 2026-11-15-navigation-specs, design.md.
Requirements
Requirement: Navigation Document
The navigation's structure SHALL be a JSON document {version, nodes}: version an integer (1 for this spec) and nodes the top level, in order. A node SHALL be {id, label} with exactly one of view (a View Id), page (a page name, page-specs) or children (nodes), and MAY carry emphasis (primary or secondary), a hint a client may ignore, and protected (Protected Nodes). The document MAY carry $schema (Published Schemas). Ids SHALL be identifiers (lower-case letters, digits and _, at most 32, with a letter), unique among siblings. Nodes SHALL nest at most a configured depth (the setting maxDepth, default 4 levels including the top).
Scenario: Pages under Config
- WHEN the top level holds
{"id": "config", "label": "Config", "children": [{"id": "pages", "label": "Pages", "view": "pages"}]} - THEN every client SHALL offer Config with Pages below it, each drawn by its own representation
Scenario: A page as a node
- WHEN a node under Trading is
{"id": "overview", "label": "My overview", "page": "stopped_workers"} - THEN opening it SHALL render the page
stopped_workers(shared or the user's own)
Requirement: Structure Without Representation
The document SHALL describe what exists and how it is grouped, never how it is drawn: it SHALL hold no widget kinds (tab, menu, sidebar), positions, sizes, keys, styles, URLs or markup, and validation SHALL refuse fields it does not define. How a client draws each level SHALL be that client's Representation Profile.
Scenario: A representation field
- WHEN a node carries
"as": "tab" - THEN validation SHALL refuse the document, naming the field's path
Requirement: View Ids
Each built-in view of the operator clients SHALL have a stable View Id: home, world, instruments, orderbook, indicators, portfolio, pnl, risk, strategy, scenario, workers, connections, triggers, states, eventstores, alerts, changes, events, services, pages, navigation. A view MAY appear more than once. A client SHALL show a placeholder naming a view it does not have, and the rest of the navigation SHALL work.
Scenario: A view the client lacks
- WHEN a node names the view
riskand the client has not built it - THEN the node SHALL open a placeholder that names the view
Requirement: Navigation Sources and Precedence
A client SHALL ship a built-in default structure (the operator-clients Navigation groups). A context MAY hold a shared structure in the state store under the virtufin.pages/navigation name (domain-devkit, cfg.navigation); saving or removing it SHALL be a write (admin only), saved with publish_change, and a client SHALL follow the state-change events to apply a new one without a reload. A user MAY keep a structure of their own per client. The client SHALL use the user's structure if it validates, else the shared one if it validates, else the built-in default, and SHALL show which is in use; a context switch SHALL resolve it again.
Scenario: An admin shares a structure
- WHEN an admin shares a structure on a context
- THEN it SHALL be saved at
cfg.navigation, announced, and every client following the context without a structure of its own SHALL use it
Scenario: A broken shared structure
- WHEN the shared structure does not validate
- THEN the client SHALL use the built-in default and say that the shared structure is invalid, with its errors
Requirement: Always Reachable
Whatever structure is in use, the pages and navigation views SHALL stay reachable: when a structure lacks them, the client SHALL append a node config (Config) holding the missing ones, each protected, so no document can lock a user out of repairing it.
Scenario: A structure without the navigation view
- WHEN the structure in use has no node for
navigation - THEN the client SHALL offer Config with Navigation (and Pages, if missing too)
Requirement: Navigation Validation
A client SHALL validate a structure when it loads one and before it saves one, and report each error with its JSON path (e.g. /nodes/1/children/0/view): an unknown version, a missing, malformed or duplicate id, a node with none or more than one of view, page, children, an unknown field, nesting beyond maxDepth. An unknown View Id and a page that does not exist SHALL NOT be errors. Saving an invalid structure SHALL be refused.
Scenario: Two targets
- WHEN a node has both
viewandpage - THEN validation SHALL fail with the node's path
Requirement: Representation Profiles
Each client SHALL define, in its own spec, a representation profile that binds each depth of the structure to one of its level kinds, a default profile, and what it does with levels deeper than the profile names. A profile SHALL be kept per client and per user, SHALL NOT be stored in the shared structure, and SHALL NOT change which nodes exist or what they open.
Scenario: One structure, two clients
- WHEN the web app and the TUI follow the same shared structure
- THEN both SHALL offer the same nodes in the same order, each drawn by its own profile
Requirement: Published Schemas
The structure SHALL be published as a JSON Schema (draft 2020-12), navigation.v1.schema.json, and each client's representation profile as a schema of its own; each schema SHALL carry an $id under which it is served without sign-in. A document MAY name its schema in $schema, so editors check and complete it. A client's validator and its published schema SHALL be kept from drifting (generated from one another, checked in CI). The rules a JSON Schema cannot state (ids unique among siblings, maxDepth, Always Reachable) SHALL stay in Navigation Validation and the vectors.
Scenario: Editing in an editor
- WHEN a user writes a structure in an editor with
"$schema": "https://app.virtufin.com/schemas/navigation.v1.schema.json" - THEN the editor SHALL flag a node with two targets or an unknown field before the document is loaded
Scenario: Validator and schema agree
- WHEN the client's validator changes and the published schema does not
- THEN its CI SHALL fail
Requirement: Navigation Conformance
Clients SHALL pass shared conformance vectors for the structure: valid and invalid documents with their expected errors, and source combinations with the structure expected in use (including Always Reachable). Representation is tested by each client.
Scenario: Vectors in CI
- WHEN a client's CI runs
- THEN it SHALL run the navigation vectors and fail on any difference
Requirement: Protected Nodes
A node marked "protected": true SHALL be movable but not removable in an editor of the structure: an editor SHALL NOT offer to remove it, nor a group holding it, and SHALL refuse to save or share a structure that drops or unprotects a protected entry. An entry SHALL count by what it opens (view, page), so it may move anywhere; a protected group by its place. The protected entries SHALL be those the built-in structure marks (the floor, so a structure written before an entry was protected keeps it) together with those the structure in use marks; an editor SHALL set the flag on the matching nodes when it opens a structure. The built-in structure SHALL mark pages and navigation. Which nodes are protected is configuration (the structure document), not client code; Always Reachable stays the safety net of every client.
Scenario: Move but not remove
- WHEN a user edits a structure whose Pages node is protected
- THEN the editor SHALL let Pages move to another group and SHALL NOT offer to remove it or the group holding it
Scenario: Unprotected in JSON
- WHEN the user removes
protectedfrom Pages in the JSON editor - THEN Save and Share SHALL refuse, naming
view:pages
Scenario: A structure shared before the flag
- WHEN the shared structure has no
protectedflags - THEN the editor SHALL still protect Pages and Navigation (the built-in floor) and the next save SHALL carry the flags