.iwc language reference

.iwc files are strict JSON with a fixed shape per file type. There is no separate syntax to learn: what you learn is the vocabulary — which keys each file takes, what values they accept, and three conventions on top of JSON: expressions, bindings and file references. This page is the map; each section links to the full guide.

File structure

Every file is one JSON object. Its type comes from the file name, <your-name>.<type>.iwc, except the two fixed files app.iwc and package.iwc.

{
  "name": "About",
  "route": "/about",
  "layout": "main.layout.iwc",
  "title": "About us",
  "sections": [{ "type": "text", "variant": "h1", "content": "About us" }]
}

Rules that apply to every file:

The full list of keys per file type is in file types; app.iwc is in app configuration.

File types

Properties and data types

Values in .iwc files are JSON values. On top of them, IWC uses a few recurring formats, each validated by the compiler:

Field types (schemas)

Tables declare their columns as fields with a type:

Every field also takes required, unique, index, default, sensitive and description. See Database.

Field specs (requests and action input)

APIs (request.payload, request.query) and actions (input) validate incoming values with field specs:

{ "type": "string", "required": true, "minLength": 2, "maxLength": 120, "trim": true }

Undeclared keys are always rejected. See Forms & validation.

Expressions

A string that starts with = is an expression, evaluated on the server:

{ "type": "text", "content": "=concat(product.name, ' — ', format(product.price, 'currency', 'USD'))" }

In scope: the current record's fields, component props, the page's named data, and always params, query, user, auth, page and app. Expressions cannot loop, assign, define functions or reach the network, and each evaluation has a budget. Inside actions, condition, items and string set.value are expressions without the =. Full reference: Expressions & page data.

Conditions

Conditional rendering uses visible, decided on the server — hidden elements are never sent to the browser:

{
  "type": "column",
  "elements": [
    { "type": "link", "label": "Sign in", "target": "/login", "visible": { "auth": "signed-out" } },
    { "type": "link", "label": "Admin", "target": "/admin", "visible": { "roles": ["admin"] } },
    { "type": "badge", "content": "Low stock", "visible": "=product.stock < 5" }
  ]
}

In business logic, conditions are steps: require fails the action unless a condition holds, and if branches:

{ "operation": "require", "condition": "product.stock >= input.quantity", "status": 409, "error": "=concat('Only ', product.stock, ' left')" }

Bindings

Bindings connect elements to data without expressions:

Data sources are DATABASE.<table>, API.<name>, STATIC, USER and STATE.<store>.<list>. See Data binding.

Events and actions

There are three kinds of "something happens":

1. UI actions on buttons and links: navigate, open, close, toggle, scroll, state, api, logout, share, install, notifications, sync, pay, tracking, native. Forms have submit.success (message, reset, navigate, redirect, mutation, reload). See the button element.
2. Server actions: .action.iwc files run by APIs, other actions (callAction), events and jobs.
3. Events and jobs: an action emits an event; the .event.iwc file's handlers run an action or queue a job. A .job.iwc runs an action in the background — queued with enqueue, or on a schedule.

Reusable definitions

Validation

Validation happens at three points:

1. Compile time — iwc check validates every file against its schema and every reference. A project that compiles has no dangling references.
2. Request time — every API validates its body, query and path parameters against its field specs and rejects undeclared fields with 422.
3. Write time — schema field rules are enforced on every write, including writes from actions, so no path stores an invalid row.

Error handling

{
  "type": "stack",
  "data": { "source": "API.products" },
  "item": { "type": "text", "bind": "name" },
  "empty": { "type": "text", "content": "No products yet." },
  "error": { "type": "text", "content": "Products could not be loaded." }
}

JSON Schemas

iwc schema --out <dir> writes one JSON Schema (draft 2020-12) per file type; iwc create puts them in .vscode/iwc-schemas/ and maps them in .vscode/settings.json, so VS Code completes and checks every key as you type. The same schemas drive the element reference.