ambleloftForm YAML reference
Look up templates, fields, submission actions and bindings. The SDK form.schema.json and CLI semantic checks define validation.
Browse contracts, signatures, fields and examples. Unspecified defaults are not inferred.
On this page
01Template root
Use either fields or steps, never both. Unknown fields are rejected. Do not add $schema, scripts or localization keys to the YAML. Associate the schema through editor settings.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| version | 1 | Yes | Unspecified | Required; exactly 1. |
| id | string | Yes | Unspecified | Required; ^[a-z][a-z0-9-]{0,79}$. |
| title / description | string | title required | Unspecified | title: 1–120 characters; description: at most 2000. |
| fields | Field[] | Conditional | Unspecified | Single-step mode: 1–100 fields. |
| steps | Step[] | Conditional | Unspecified | Multi-step mode: 1–20 steps; id, title and fields required, next optional. |
| submit | object | Yes | Unspecified | Required; kind: chat or kind: operation. |
02Common field properties
Fields require name, type and label. Keep names unique in their scope and consistent with bindings. CLI validation additionally checks type-specific combinations.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| name | string | Yes | Unspecified | ^[a-z][a-z0-9-]{0,79}$. |
| label | string | Yes | Unspecified | 1–120 characters. |
| required | boolean | No | Unspecified | Optional boolean. |
| help / placeholder | string | No | Unspecified | help: at most 2000 characters; placeholder: at most 200. |
03Seven field types
Fields are statically declared. Attachments, password inputs, remote dynamic options and conditional scripts are unsupported. Respect the declared money precision rather than accumulating financial amounts as floating-point values.
| Field / API | Contract |
|---|---|
| text / textarea | minLength and maxLength: 0–20000. |
| number | minimum, maximum; integer controls integral input. |
| money | currency: three uppercase letters; scale: 0–4; use decimal strings for limits, e.g. '0.01'. |
| date | Date input. |
| select | 1–100 static options; each label/value is 1–120 characters. |
| checkbox | Boolean checkbox; use required for mandatory confirmation. |
04Submission actions
operation binds to a declared operation in the same extension. Input bindings and recovery targets undergo semantic validation. Writes still require host confirmation.
| Field / API | Contract |
|---|---|
| chat | Requires kind and label; no operation or input. |
| operation | Requires kind, label, operation and input; recovery optional. |
| input | At most 100 properties, each {from: path} or {value: literal}. |
| recovery.operation | A page-exposed read operation in the same extension, queried by submissionId. |
05Editor and runtime validation
With a YAML-schema editor extension installed, add this to .vscode/settings.json. Static schema checks do not replace CLI binding validation or host runtime permission checks.
{
"yaml.schemas": {
"./node_modules/@ambleloft/extension-sdk/form.schema.json": [
"skills/**/*.yaml"
]
}
}