Logos Language Syntax Specification

Purpose

This specification defines the syntax and parsing behavior of the Logos language parser, from the user and architect perspective. It describes the functionality and principles of how the environment interprets .model and .view files. Instead of raw grammar code, it presents a logical description of parsing behavior.

Scope

This document covers:

• the indentation-based syntax philosophy of Logos,
• file headers and versioning,
• comments,
• entity definitions (elements, gateways, facts, relationships),
• identifier formats (UUID and LIBERAL_ID) and their auto-transformation,
• attribute syntax and localization (I18n),
• the alias directive for domain terminology,
• the include directive for modular files,
• the top-level structure of .view files (Board and Dashboard).

Non-Goals

This document does not cover:

• the semantics of .interaction files (see LogosInteractionFileSpec.md),
• the SVO/BPMN projection model,
• the .fact file format,
• runtime execution or ledger semantics,
• renderer implementation details for Board/Dashboard widgets.

Terminology

Model or Contract

A Logos file is a graph description built from indentation-scoped blocks. The minimal shape of a valid file is:

soter v1
# soter commit: <hash>            (optional provenance comment)

element u-<UUID>:
    name: "Friendly Name"
    key: value

relationship u-<UUID>:
    source -> target
    key: value

.view files use the same indentation grammar but are rooted in exactly one of two container types:

Board:
    Diagram: ...
    Simulation: ...

Dashboard:
    Widget: ...

Rules

Syntax philosophy (indentation-based)

• Logos is a declarative language whose syntax is based on indentation (similar to Python).
• Curly braces {} and semicolons ; are not used.
• Hierarchy (e.g., attributes belonging to an element) is defined by increasing the indentation level.
• The parser strictly enforces indentation consistency, which forces clean code and simplifies tracking changes in version control systems (such as Git).

Headers and versioning

• Every valid file must start by declaring the language version. The default starting point is the declaration soter v1.
• Optionally, a special comment (called "provenance") can be placed under the header, e.g., # soter commit: [hash], linking the file to a specific point in modification history.

Comments

• Single-line: starting with the # character.
• Multi-line: blocks of text enclosed in triple apostrophes '''.
• Comments are ignored by the parser and serve purely documentary purposes.

Defining entities (graph construction)

Building a model means declaring graph nodes and edges.

Elements, gateways, and operational facts

• Defining a single "node" starts with the keyword element, gateway (for base models), or fact (for operational blocks on Ledgers), followed by an identifier.
• UUID is mandatory in definition headers: the parser accepts identifiers in UUID format (strict) and LIBERAL_ID format (for legacy support). The prefix u- is required only in definition headers.
• References within blocks (attributes such as source:, from:, to:, in:, and out:) MUST use friendly names defined in the name: field of the target element. Using UUIDs inside blocks is not allowed and is a validation error.
• LIBERAL_ID allows hyphens, a leading digit, and any alphanumeric characters to enable automated migration to UUIDs.
• Auto-UUID Transformation: during the load step, LIBERAL_ID identifiers are mapped to stable UUIDs, and then LogosTracer replaces them in the source file (In-place Source Modernization).
• All attributes of a node are defined on subsequent lines after an indentation (the node's body).

Relations (edges)

• Relations (connections between elements) are initiated with the word relationship, followed by an identifier in the same u-<UUID> format.
• The flow direction is specified using an arrow -> (e.g., Source -> Target).
• Relations, like elements, create their own block (indentation) where their attributes (such as relationship type) can be specified.

Attribute flexibility and localization (I18n)

• Within element and relation blocks, attributes are defined in key: value format.
• The @ modifier binds localization to attributes (e.g., name@pl: "Umowa", name@en: "Contract").
• Attribute values can be a single-line string, a number, a text reference, a nested indented block of logic, or a bulleted list using hyphens -.

Aliases — domain alignment

• Logos has a built-in alias directive, allowing keywords to be replaced with the organization's own terminology.
• For example, alias element as node causes the parser to correctly process definitions starting with node.
• This relieves architects of the need to write long words and permits modeling using domain jargon (e.g., alias Action as Steps).

Ecosystem modularity (include)

• The directive include "path/to/file.model" enables merging multiple smaller model files into a single, cohesive executable entity.
• File hierarchy resolution occurs during the load step, protecting designers from "single giant file hell."

Defining views and data presentation (.view files)

The Board/Dashboard root-element contract, the Diagram/Simulation/ Widget vocabulary, and the .view dependency boundary are specified in LogosViewFileSpec.md; not repeated here.

Examples

Element with a friendly name and localized attribute:

element u-3f9a1b2c-...:
    name: Contract
    name@pl: "Umowa"
    name@en: "Contract"

Relationship referencing elements by friendly name (not by UUID):

relationship u-7c2d4e10-...:
    source -> target
    type: precedes

Alias directive redefining domain terminology:

alias element as node
alias Action as Steps

Include directive for modular files:

include "shared/parties.model"

Validation

• The parser enforces strict, consistent indentation; inconsistent indentation is a parse error.
• Using a UUID (instead of a friendly name:) inside a reference attribute (source:, from:, to:, in:, out:) is a validation error.
• LIBERAL_ID identifiers are accepted only as a legacy/migration path; they are auto-transformed to UUIDs at load time.
• .view files must have exactly one root container (Board or Dashboard); the two cannot coexist at the same level or contain each other.
• Board may only contain Diagram and Simulation definitions; Dashboard may only contain Widget definitions.

Compatibility

• LIBERAL_ID exists specifically to support legacy files during automated migration to strict UUID identifiers. LogosTracer performs In-place Source Modernization so that source files converge on UUIDs over time.
• The alias directive allows organizations to adopt domain-specific terminology without diverging from the underlying grammar, preserving compatibility with tooling that consumes canonical keywords.

Open Questions

• None captured in the source material.

Related Documents

• DocumentationStyleGuide.md - writing profile and structure rules applied to this document.
• TechnicalSpecTemplate.md - template this document follows.
• LogosOverview.md - entry point for the Logos language documentation set.
• ArchitectureOverview.md - implementation scope context.
• LogosInteractionFileSpec.md - operational UI counterpart to .view, built on the same Logos element grammar.
• LogosFactFileSpec.md - .fact block syntax built on this grammar.
• LogosSvoSemanticsSpec.md - SVO process semantics and BPMN translation rules that operate on models written in this syntax.