Logos View File Spec

Purpose

This specification defines the file-level contract for .view files: the read-side query layer (CQRS Query) that projects .model and .fact data into analytical and operational visual surfaces, without introducing new domain entities.

.view answers "how should the model or facts be observed?" It must not answer "what can exist or happen?" (.model), "what was recorded as having happened?" (.fact), or "how are operational inputs captured?" (.interaction).

Scope

This document covers:

• the Board (analytical) and Dashboard (operational) root-element kinds and what each may contain;
• the dependency rule that bounds what a .view file may reference and must not define;
• the current grammar negative rules and open vocabulary questions shared with .interaction.

Non-Goals

• This document does not define the base Logos lexical grammar; see LogosLanguageSpec.md.
• This document does not define .model, .interaction, .fact, or .api file contracts; see LogosModelFileSpec.md, LogosInteractionFileSpec.md, LogosFactFileSpec.md, and LogosApiFileSpec.md.
• This document does not define the VGM projection pipeline or BPMN/UML rendering rules; see ProjectionOverview.md and ProjectionConfigurationCascadeSpec.md.

Terminology

Model or Contract

Root Elements: Board and Dashboard

For the query/read layer (CQRS Query), a strict division is applied in .view files:

• Board (Analytical): operates in the model verification and forecasting space. It can only contain definitions of type Diagram (static rendering of .model nodes) and Simulation (data simulation based on hypothetical .fact files).
• Dashboard (Operational): operates in the space of insight into the current state of reality. It can only contain definitions of type Widget (which have their own subtypes like tables, bar charts, powered by specific queries on the .fact graph).

In a .view file, the root element defining the target of data display is always Board or Dashboard. They cannot exist simultaneously at the same level nor contain each other.

Dependency Boundary

Rules

• A .view file's root element must be exactly one of Board or Dashboard, never both, and neither may contain the other.
• Board children are restricted to Diagram and Simulation; Dashboard children are restricted to Widget (and its subtypes).
• A .view file must not define new domain entities. It may only reference elements already defined in .model and facts recorded in .fact.
• The grammar for .view's (and .interaction's) core concepts (View, Widget, Form, Field) is not yet finally closed.
• We do not use the word button, because it too strongly suggests a specific UI implementation.
• We do not use the word action, because this concept is already reserved in the Logos ontology (see PhilosophyConstitution.md).

Examples

An analytical Board containing a Diagram referencing .model elements (a concrete .view-element attribute example, including standard/target resolution, is in ProjectionConfigurationCascadeSpec.md):

Board OrganizationBoard
    Diagram OrgChart
        renders: MainBoard model elements

An operational Dashboard containing a Widget:

Dashboard OperationsDashboard
    Widget OpenOrdersTable
        query: open orders from .fact graph

Validation

The parser and strict-mode linter enforce the Board/Dashboard root-element exclusivity rule and reject .view files that attempt to define new domain entities rather than reference existing .model/.fact data.

Compatibility

The Board/Dashboard/Diagram/Simulation/Widget vocabulary is stable. The remaining .view/.interaction concept vocabulary (View, Widget, Form, Field) is not yet finally closed; see Open Questions.

Open Questions

• The semantics of .view/.interaction core concepts (View, Widget, Form, Field) are not yet finally closed. The semantic equivalent of a "button" in .interaction remains particularly important.
• The current best working candidate for the button-equivalent concept is Command, since this term appears in the master CBF operational aspects table for .interaction and in the accompanying documentation describing operational components. This does not close the entire .interaction/.view vocabulary; it means further work should start from Command, not from implementation terms like button. See LogosInteractionFileSpec.md for the current Command element.

Related Documents

• LogosLanguageSpec.md - base Logos lexical grammar that .view files are written in.
• LogosModelFileSpec.md - the read source .view projects from.
• LogosInteractionFileSpec.md - the write-side counterpart sharing the open Command/vocabulary question.
• LogosFactFileSpec.md - the ledger source Widget and Simulation definitions query.
• ProjectionOverview.md - how .view content is rendered into visual outputs.
• ProjectionConfigurationCascadeSpec.md - configuration cascade that resolves .view rendering options.
• PhilosophyConstitution.md - the CQRS of Reality axiom and the dependency matrix this file implements.
• LogosOverview.md - entry point for Logos documentation.
• DocumentationStyleGuide.md - writing profile and document-type rules.
• TechnicalSpecTemplate.md - technical document template.