# Concepts

<PageBadges />

## Schema-first

A form0 schema is a JSON document with a top-level `form` object. The schema defines the
structure, rules, and behavior of a form without any UI code.

## Fields and values

- Each field has a `data_name` (human-readable identifier) and a `key` (internal identifier, typically derived from `data_name`).
- Engine values are stored by `data_name`.
- Conditions reference fields by `field_id`. You can use either `key` or `data_name`; using `data_name` is often more practical when writing schemas manually since it's more memorable.

## Engine state

The engine evaluates the schema and produces a state object with:

- `values`: current field values
- `errors`: validation errors
- `visible`: visibility flags per field
- `required`: requirement flags per field
- `read_only`: read-only flags per field

## Data flow

1. Load the schema and create the engine
2. Provide initial values (optional)
3. Fire any initialization events
4. Evaluate: calculations, conditions, and validation
5. On each value change:
   - Update the value
   - Re-evaluate (live validation)
   - Fire change events if defined
6. Read state or build a structured record for submission

## Events and expressions

- Calculated fields use expressions, inside `calculate` property, like `$age + 1` to derive values from other fields.
- Events live in `form.events.code` and can react to form changes at runtime (e.g., when a record is loaded or a field changes).