# Language reference

Complete reference for Rootform language 0.1.0 source units, declarations, expressions, evaluation, and diagnostics.

Rootform language is a closed, statically validated language for two jobs:

- Dialects interpret managed and data resource instances from plan JSON or state JSON.
- Policy Packs evaluate the resulting architecture without reading raw infrastructure values.

HCL supplies lexical syntax for `.rf.hcl` and `.rf.json`. Rootform defines the
accepted blocks, attributes, expressions, references, types, defaults, and
runtime meaning. General HCL or Terraform expressions are not implicitly part
of RF.

This reference documents Rootform language version `0.1.0` and is normative.
For motivation and worked examples, start with the [learning path](https://docs.rootform.dev/language/#learn).

## How to use this reference

### Source units

| Page | Contract covered |
| --- | --- |
| [Syntax and files](https://docs.rootform.dev/language/reference/syntax-files/) | Source discovery, native and JSON syntax, structural grammar, names, versions, and source-unit boundaries |
| [Symbols and references](https://docs.rootform.dev/language/reference/symbols/) | Canonical IDs, local and qualified references, resolution, and duplicate rules |
| [RF Vocabulary](https://docs.rootform.dev/language/reference/rf-vocabulary/) | Complete embedded `rf.*` vocabulary and exact meanings |

### Dialects

| Page | Contract covered |
| --- | --- |
| [Dialect declarations](https://docs.rootform.dev/language/reference/dialects/) | `dialect`, `provider`, `concept`, `context`, and `relation` |
| [Rules and matching](https://docs.rootform.dev/language/reference/rules/) | `rule`, `match`, managed and data instance kinds, predicates, and selection |
| [Fact emissions](https://docs.rootform.dev/language/reference/emissions/) | `context`, `relation`, `contribution`, explicit attribute matching, and omissions |
| [Composition](https://docs.rootform.dev/language/reference/composition/) | Ordered members, per-instance resolution, and unresolved-member reasons |

### Expression language

| Page | Contract covered |
| --- | --- |
| [Expressions](https://docs.rootform.dev/language/reference/expressions/) | Literal types, expression grammars, operators, precedence, and rejected syntax |
| [Traversals and scope](https://docs.rootform.dev/language/reference/traversals/) | `source`, `provider`, `target`, `member`, path steps, and position rules |
| [Built-ins](https://docs.rootform.dev/language/reference/built-ins/) | Complete signatures and parameters for `exists`, `length`, and architecture queries |

### Policies

| Page | Contract covered |
| --- | --- |
| [Policy Packs](https://docs.rootform.dev/language/reference/policy-packs/) | `policy_pack`, `policy`, `target`, linking, messages, and target intersections |
| [Evaluation](https://docs.rootform.dev/language/reference/evaluation/) | Rule precedence, three-valued evidence, query completeness, outcomes, and exit status |

[Diagnostics and limits](https://docs.rootform.dev/language/reference/diagnostics/): Stable codes, severity, source ranges, and all author-facing bounds

## Construct index

Cardinality applies across one source root unless a placement says otherwise.

| Construct | Source unit | Placement | Cardinality | Label | Detail |
| --- | --- | --- | --- | --- | --- |
| `dialect` | Dialect | Top level | Exactly 1 | Required | [Dialect declarations](https://docs.rootform.dev/language/reference/dialects/#dialect-block) |
| `provider` | Dialect | Inside `dialect` | 0 or more; at least 1 when unit has a Rule | Required | [Provider block](https://docs.rootform.dev/language/reference/dialects/#provider-block) |
| `concept` | Dialect | Top level | 0 or more | Required | [Semantic definitions](https://docs.rootform.dev/language/reference/dialects/#semantic-definition-blocks) |
| `context` definition | Dialect | Top level | 0 or more | Required | [Semantic definitions](https://docs.rootform.dev/language/reference/dialects/#semantic-definition-blocks) |
| `relation` definition | Dialect | Top level | 0 or more | Required | [Semantic definitions](https://docs.rootform.dev/language/reference/dialects/#semantic-definition-blocks) |
| `rule` | Dialect | Top level | 0 or more | Required | [Rules](https://docs.rootform.dev/language/reference/rules/#rule-block) |
| `identity` | Dialect | Inside `rule` | 0 or 1 | Forbidden | [Identity and endpoint declarations](https://docs.rootform.dev/language/reference/rules/#identity-and-endpoint-declarations) |
| `endpoint` | Dialect | Inside `rule` | 0 or 1 | Forbidden | [Identity and endpoint declarations](https://docs.rootform.dev/language/reference/rules/#identity-and-endpoint-declarations) |
| Rule `match` | Dialect | Inside `rule` | Exactly 1 | Forbidden | [Matching](https://docs.rootform.dev/language/reference/rules/#match-block) |
| `context` emission | Dialect | Inside `rule` | 0 or more | Optional, exclusive with `as` | [Context emission](https://docs.rootform.dev/language/reference/emissions/#context-emission) |
| `relation` emission | Dialect | Inside `rule` | 0 or more | Optional, exclusive with `as` | [Relation emission](https://docs.rootform.dev/language/reference/emissions/#relation-emission) |
| `contribution` emission | Dialect | Inside `rule` | 0 or more | Forbidden | [Contribution emission](https://docs.rootform.dev/language/reference/emissions/#contribution-emission) |
| Fact `match` | Dialect | Inside an emission | 0 or 1 | Forbidden | [Explicit attribute match](https://docs.rootform.dev/language/reference/emissions/#explicit-attribute-match) |
| `composition` | Dialect | Inside `rule` | 0 or 1 | Forbidden | [Composition](https://docs.rootform.dev/language/reference/composition/#composition-block) |
| `member` | Dialect | Inside `composition` | 1 or more | Required | [Member](https://docs.rootform.dev/language/reference/composition/#member-block) |
| Member `match` | Dialect | Inside `member` | Exactly 1 | Forbidden | [Member matching](https://docs.rootform.dev/language/reference/composition/#member-matching) |
| `policy_pack` | Policy Pack | Top level | Exactly 1 | Required | [Policy Pack manifest](https://docs.rootform.dev/language/reference/policy-packs/#policy_pack-block) |
| `policy` | Policy Pack | Top level | 0 or more | Required | [Policy](https://docs.rootform.dev/language/reference/policy-packs/#policy-block) |
| `target` | Policy Pack | Inside `policy` | Exactly 1 | Forbidden | [Target](https://docs.rootform.dev/language/reference/policy-packs/#target-block) |

## Closed expression surface

| Area | Accepted values |
| --- | --- |
| Literal values | String, Boolean, non-negative number literal with exact signed 64-bit integer value |
| Unary operators | `!` |
| Binary operators | `&&`, <code>&#124;&#124;</code>, `==`, `!=`, `<`, `<=`, `>`, `>=` |
| Traversal roots | `source`, `provider`, `target`, `member.<name>`, each restricted by position |
| Policy wrappers | `exists(query)`, `length(query)` |
| Policy queries | `contexts(...)`, `relations(...)`, `contributions(...)` |

`where` and `assert` do not accept collections, object values, `null`,
floating-point values, arithmetic, conditionals, comprehensions, splats,
dynamic indexes, or arbitrary function calls. Static string fields use
result-based constant HCL evaluation, and dedicated Policy target fields accept
closed list syntax.

## Reference conventions

Parameter tables use these meanings:

| Term | Meaning |
| --- | --- |
| Required | Author must provide value or block. |
| Optional | Author may omit value or block. |
| Default | Value compiler uses when optional attribute is absent. |
| Static | Value must evaluate in empty HCL context; variables and runtime data are unavailable. |

Unknown attributes, blocks, functions, and expression shapes fail closed with
a diagnostic. They are never preserved for later evaluation.