YAML Formfield

A dedicated YAML editor field with syntax highlighting, validation, and file import/export capabilities for structured configuration data.

Properties

Attribute Comments
basic
name
string / required / unique

Field name
Alfanumeric + underscore + dash

This attribute represents the name of the form field.
type
string / required

Field type

Other attributes might only be available for some field types.

Value:
yaml
label
string

Field label
Free text

A friendly name/label for the field. Note: if not set, the field name is used as label, but not when type is html.

Since 6.0.3: Supports placeholders for dynamic labels (e.g., Label: $(fieldname)).
help
string

Field help message
Free text

Some fields require additional help information. This help message will be shown below the field.

Since 6.0.3: Supports placeholders for dynamic help text (e.g., This field depends on $(fieldname)).
subform
string / required

Name of the subform that defines one row

For a list field: delegates the per-row editor to a subform.
For a yaml field: the value is a single object edited via a subform drilldown instead of a raw YAML editor.
Set this property to the name of a top-level form of type subform declared in the same forms file (or in any loaded forms file).
The same subform can be referenced by multiple fields, enabling reuse (e.g. a single Address subform shared across several forms).
data
default
many

Default value

The type of the value depends on the field type.
Can be string,boolean, number, array or object. When using multiple, the default must be an array.
When using an enum field, you can use the following special values :

  • __auto__ : select the first
  • __none__ : select none
  • __all__ : select all (if multiple is true)

For table fields, the default must be an array of objects matching the tableFields structure. For yaml fields, the default can be any valid YAML structure (object or array).
interaction
dependencyFn
string
added in version 4.0.0

The dependency logical function

This attribute represents the logical function between multiple dependencies.

Choices:
  • and (default)
  • or
dependencies
list / elements=object

Show/hide this field based on the values or other fields
Reference to other formfields and their values

Each dependency element is either an object with the following 2 attributes:

  • name : holds the fieldname.
  • values : a list of valid values for the referenced field.

Or with the following 2 attributes:

  • name : holds the fieldname.
  • isValid : a boolean to check if the referenced is validated or not.

Use in combination with attribute dependencyFn.
showLoadButton
boolean
added in version 6.1.5

Show load button for file import

Enables a “Load YAML” button that allows users to import data from .yml or .yaml files. For table fields, the YAML file must contain a valid array of objects. For yaml fields, the file can contain any valid YAML structure. Single objects are automatically wrapped in arrays for table fields.

Default:
false
showDownloadButton
boolean
added in version 6.1.5

Show download button for file export

Enables a “Download” button that exports the field content as a .yml file. The filename is automatically generated from the field name.

Default:
false
readonly
boolean
added in version 6.1.5

Display YAML in readonly mode

When set to true, displays the YAML content with syntax highlighting in a non-editable card. Useful for showing computed or retrieved YAML data without allowing modifications. The field uses v-highlightjs for pretty syntax-highlighted display.

Default:
false
output
output
boolean
added in version 6.2.0

Include field value as extravar

Form fields are by default sent as extravars.
Set to false to exclude a field from the extravar output.

Note: noOutput: true is the deprecated equivalent — please migrate to output: false.

Default:
true
noOutput
boolean

Do not output as extravar (deprecated)

Deprecated since 6.2.0. Use output: false instead.
Form fields are by default sent as extravars.
If you do not want a field to be sent as extravar, set this attribute to true.

Default:
false
model
string or array

Extravar modelling
An dot-based string notation of an object, or an array of these

By default, a field is sent as a root-extravar.
If you want model the output of the extravars, you can specify a dot-notation of how this field should be modelled.
security
noLog
boolean
added in version 2.2.3

Disable backend logging

Disables logging in the backend, to hide passwords for example.

Default:
false
validation
required
boolean

Required field

Makes the field required.

Default:
false
validIf
object
added in version 2.2.4

An field based validation (field must be true)

Enforces a validation where a referencing (expression) field must be true. This field requires an object with 2 attributes:

  • field : The name of the referencing field
  • description : A validation message to show when the validation is not met. (Since 5.0.1: Supports placeholders for dynamic messages)
validIfNot
object
added in version 2.2.4

An field based validation (field must be false)

Enforces a validation where a referencing (expression) field must be false. This field requires an object with 2 attributes:

  • field : The name of the referencing field
  • description : A validation message to show when the validation is not met. (Since 5.0.1: Supports placeholders for dynamic messages)
ignoreIncomplete
boolean

Allow form submit on non-evaluated placeholders

When an expression-based field has placeholders,
the default form behaviour is not to allow form submit until all placeholders are resolved. When this attribute is true, the form does not wait for placeholder completion for this field.

Default:
false
yamlError
object
added in version 6.1.5

Custom YAML validation error message

Allows you to customize the error message displayed when YAML syntax validation fails. The yamlError object requires a description property containing the custom message. Supports placeholders for dynamic error messages.
visualization
group
string

The field group name
Free text

With this attribute you can group fields together.
When all fields in a group are hidden (due to dependencies), the group is also hidden.
line
string
added in version 4.0.3

The field line name
Free text

With this attribute you can group fields in a single line together.
Use together with the width parameter to set the width, if not, the width is auto.
width
string
added in version 4.0.3

The field width
A valid Bootstrap Column width

With this attribute you can set the width of a field.
Use together wit the line parameter to put fields on 1 line. see https://getbootstrap.com/

Choices:
  • col-1
  • col-2
  • col-3
  • col-4
  • col-5
  • col-6
  • col-7
  • col-8
  • col-9
  • col-10
  • col-11
  • col-12

Examples

Manual YAML editing 

- type: yaml
  name: config
  label: Application Configuration
  default:
    database:
      host: localhost
      port: 5432
    features:
      - authentication
      - logging
  showLoadButton: true
  showDownloadButton: true
  yamlError:
    description: "Please enter valid YAML configuration"
  required: true

YAML from expression 

- type: yaml
  name: users
  label: User List
  expression: fn.fnRestBasic('get','https://api.example.com/users','','','')
  showDownloadButton: true
  readonly: true

YAML from local expression 

- type: yaml
  name: computed_config
  label: Computed Config
  runLocal: true
  expression: |
    (()=>{
      return {
        env: 'production',
        settings: $(environment_field)
      };
    })()
  showDownloadButton: true

YAML from query 

- type: yaml
  name: database_data
  label: Database Records
  query: "SELECT * FROM servers"
  dbConfig: mydb
  showDownloadButton: true

Accessing parent form data via __parent__

When a yaml field uses subform mode, AnsibleForms automatically injects a __parent__ variable into the subform containing a snapshot of all parent form field values at the time the editor opens (including constants and vars).

Use it with the standard $(...) expression syntax in the subform’s field definitions:

forms:
  - name: NetworkConfig
    type: subform
    fields:
      - name: interface
        type: text
        label: Interface
        required: true

      - name: vlan
        type: enum
        label: VLAN
        # filter available VLANs based on the parent's selected region
        query: "select id,name from vlans where region='$(__parent__.region)'"
        dbConfig:
          name: MYDB
          type: mysql
        valueColumn: id
        placeholderColumn: name

      - name: mtu
        type: number
        label: MTU
        # default to 9000 in production, 1500 elsewhere
        expression: "'$(__parent__.environment)' === 'production' ? 9000 : 1500"
        runLocal: true

  - name: Configure server
    type: ansible
    playbook: configure.yml
    fields:
      - name: environment
        type: enum
        values: [dev, staging, production]

      - name: region
        type: enum
        values: [eu-west-1, us-east-1, ap-southeast-1]

      - name: nic
        type: yaml
        label: Network interface
        subform: NetworkConfig

__parent__ is stripped from Ansible extravars — it is a frontend-only helper. It is never sent to your playbook.

Copyright © 2023-2026 AnsibleForms. All rights reserved.