Language reference

This page is for lookup after the learning sequence. It describes the language's authored forms and relationship rules. Tool-specific task properties belong to their dialects.

Lexical rules

• Whitespace separates tokens. // starts a line comment; /* ... */ is a block comment. Comments do not nest.
• Double quotes delimit quoted text. Escapes are ^^, ^", ^n, ^r, ^t. Backslash is not the escape character. Quoted text has no interpolation.
• { } : ; ( ) , [ ] @ $ . + and double quote are token delimiters. A word consists of non-whitespace characters outside those delimiters. Use simple identifiers for names and quote punctuation-sensitive values and filenames.
• Definition kinds/names, property names, array entry names, and path segments use unquoted words. Target kinds and target values can also be quoted.
• Scalars are text. Bare text joins token pieces with spaces; quoted text preserves its contents. For example, quote "1.5" to retain the decimal spelling instead of relying on bare token reconstruction.
• + composes scalar text. There are no arithmetic, comparison, function-call, loop, or statement-level conditional operators in this syntax.

Declaration grammar

The following notation uses { ... } for repetition, [ ... ] for optional parts, and quoted punctuation for literal tokens. bare-text means scalar text up to the containing delimiter or +; use quoted text where exact spacing or punctuation matters.

document       = { header } { definition } ;
header         = module | include | dialect | data ;
module         = "module" [ word ] quoted-path ";"
               | "module" "recursive" quoted-pattern ";" ;
include        = "include" [ "recursive" ] quoted-path-or-pattern ";" ;
dialect        = "dialect" quoted-path ";" ;
data           = "data" word quoted-path ";" ;

definition     = word word [ contributors ] { target } "{" { member } "}" ;
contributors   = "(" path { "," path } ")" ;
target         = name "[" name { "," name } "]" ;
name           = word | quoted-text ;
member         = word ":" value ";" | "$" path ":" value ";" | definition ;
value          = array | expression ;
array          = "[" [ entry { "," entry } [ "," ] ] "]" ;
entry          = [ word ":" ] ( definition | value ) ;
expression     = part { "+" part } ;
part           = quoted-text | bare-text | "@" path | "$" path ;
path           = word { "." word } ;

Dependency paths may also be unquoted where the parser can read them as one path; quoted paths are used throughout this manual. A named module selects an existing root, not a nested path or a replacement name. Pattern imports cannot have a named selector. recursive applies to whole-document file discovery.

All header declarations precede definitions. At most one dialect may be declared. A definition's contributors precede its target clauses. Properties and arrays end with semicolons; a direct definition's closing brace does not. Inline definitions occur in arrays.

Identity and casing

Identity or comparison	Rule
Ordinary definition/property/array entry lookup	Case-insensitive
Root, child, or named-entry uniqueness	Case-insensitive within its scope
Target kind/value	Case-sensitive
External qualified identity	Case-sensitive
Dialect finite AllowedValues	Case-insensitive
Physical filenames	Determined by the source provider/filesystem

A kind does not provide another namespace for same-named siblings. A property and child cannot share the same ordinary name. An ordinary Path property and an external $Path assignment are distinct identities. An explicit array entry name takes precedence over an inline/referenced definition's name as that entry's effective name. Scalar entries have no implicit name.

Lookup

Internal reference paths start with @; composition selectors omit @.

For an internal reference:

1. A single segment searches the current definition's properties/children, then an imported root of that name. It does not walk ancestors for scalars.
2. A qualified path first searches for its first member in the current scope and outward through enclosing scopes, then traverses from the matched member.
3. Otherwise, its first segment can name the current/enclosing definition or an imported root. The remaining segments traverse its members.
4. Traversal follows definition-valued properties and named array entries as well as direct children. A scalar cannot supply further member segments.

An ordinary unrelated local root is not an implicit reference namespace. Once a nearer matching member starts a path, an invalid remainder does not select an unrelated distant definition instead.

Composition selectors search from the receiving definition's parent scope. Root definitions can compose from other roots. Nested definitions can compose from sibling definitions or accessible qualified/imported definition paths. Use an explicit owner path when extending a nested contributor.

Composition rules

Contribution	Result
Several bases	Applied left to right
Local body	Applied after all bases
Scalar or array/non-array collision	Higher-precedence whole value wins
Array/array collision	Fold entries by effective name; unnamed entries accumulate
Replaced named array entry	Retains its previous position
New array entry	Appends in contributor order
Same-named child definition	Higher-precedence child replaces it as a unit
Property/child name collision	Error
Inherited references	Rebound in the receiving effective definition

Duplicate entries inside one contributor are still errors. An empty array is not a clearing operator. Target clauses are not copied from contributors. Composition, loading, and scalar-dependency cycles are rejected. Concrete object-reference cycles are allowed by compilation; emitters may constrain their representation.

Target rules

Each selected kind has one selected value. For each selected kind mentioned by a declaration, its value must occur in that declaration's clause. Values within one clause are alternatives; matching across selected kinds is conjunctive. Unselected kinds impose no filtering. An absent clause imposes no restriction for that kind. Empty clauses and duplicate kinds/values within a clause fail.

Filtering precedes composition and value resolution and reaches loaded dependencies. Duplicate-identity validation applies to the retained model. Selections are not part of definition identity. Every selected name is readable through $ and is read-only as an external identity.

Document relationships

Declaration	Reference availability	Independent artifact contribution
module	Selected root(s) under their declared identities	No
include	Does not establish a namespace	Yes
dialect	Supplies validation language, not domain imports	No
data	Separate tabular-source dependency	No ordinary definition root

Relative file paths belong to the declaring document. Includes collect entry first and recurse in declaration order; repeated sources contribute once. Patterns support * and ? in filenames and optional recursive traversal. Their expansion follows source-provider enumeration order; the filesystem provider does not sort matches. An existing folder with no matches contributes nothing; a missing folder is an error. The declaring file is excluded from its own pattern results. Named imports require an exact source and do not alias the selected definition.

Dialect rules

Language definitions use these seven kinds. Put definition rules in Definitions, property rules in Properties, and child constraints in Children arrays. The validator expects nested value/array/reference rules under the literal child names Value, Array, and Reference, respectively.

Kind	Properties and subordinate rules
Language	Definitions; UnknownDefinitions: Allow/Reject
Definition	Root; Parents; UnknownProperties; UnknownChildren; Properties; Children
Property	Required; one Value rule
Child	Required Kinds; Minimum; Maximum
Value	SourceForms; EffectiveCategories; Scalar; AllowedValues; one Array and/or Reference rule
Array	Minimum; Maximum; Names; EntrySourceForms; EntryEffectiveCategories; DefinitionKinds; AllowedValues; Mixed
Reference	Required Targets; optional DefinitionKinds

Source forms are Text, Array, Reference, TextComposition, InlineDefinition, ExternalReference. Effective categories are Text, Array, Definition. Scalar constraints are Text, Integer, Boolean. Names policies are Required, Optional, Forbidden. Reference Targets are Property and/or Definition; these are reference-kind constraints, unrelated to a declaration's target-selection clauses.

Boolean text is True or False, case-insensitively. Integer validation requires a canonical signed decimal value in the validator's integer range (-0 is also accepted); prefixes, leading zeroes, and a leading plus are not alternate spellings. Maximum: Unbounded expresses an unbounded cardinality.

Unknown-property and unknown-child policies are Allow/Reject. Parents and Children are independent constraints. Mixed controls effective array-entry categories. Included language fragments contribute additional rules; duplicate rule names do not override one another.

Defaults when a rule omits a setting:

Setting	Default
Unknown definition kinds / unknown properties	Reject
Definition allowed at root	False; declare Root: True where intended
Property Required	False
Parents	No parent-kind restriction from this rule
Unknown children	Allow unless a Children array is declared, which defaults the policy to Reject
Minimum / Maximum counts	Zero / Unbounded
Array Names / Mixed	Optional / True
Unspecified source/category/scalar constraints	No constraint of that kind

An explicit unknown-child policy overrides the default. A parent rule can still reject a child whose own Parents rule does not restrict it.

Validation checks completed structure while preserving source-form constraints. Checks requiring unresolved external text are retained for Live access. Validation does not execute the domain operations represented by the document.

External contract

$Name uses the selected target value when present, otherwise the consumer's read handler. Internal references remain bound when an expression is deferred. Live reads evaluate external text on access. Selected values belong to the compiled selection, not a changing caller-owned selection object.

$Name: expression; declares desired external state. It does not apply that state. Live distinguishes evaluation from explicit result publication. Multiple surviving public assignments to one external identity and assignments to selected targets fail. The host owns persistence and transaction semantics.

See Artifacts for projection rules, CLI for invocation, and Diagnostics for interpreting failures.