Skip to main content

Create and load schema

Schemas are defined in YAML format and follow a strict structure. Splitting a schema into multiple smaller files is recommended to keep it maintainable as it grows.

note

Enable schema validation in your editor to catch errors while writing schema files.

Once a schema file is ready, you can check it against a running Infrahub instance to verify it is valid and won't break existing data, then load it to apply the changes. Schema operations should always be performed on a branch to avoid directly affecting the main branch.

Schema file​

Most schema files use some combination of these top-level keys:

---
version: '1.0'
generics:
    - <new generics are defined here>
nodes:
    - <new nodes are defined here>
extensions:
  nodes:
    - <node extensions are defined here>

For a full reference of all available properties, see Nodes & attributes, Relationships, and Generics & inheritance.

By convention, store schema files in a schemas folder at the root of your repository.

Format schema files​

infrahubctl schema format rewrites schema files with a consistent key order, so hand-edited files read the same way and produce small diffs in version control. It operates on the files on disk and does not contact a running instance.

infrahubctl schema format <path to schema file or a directory>

By default the command only reorders the keys within each node, generic, attribute, relationship, and dropdown choice. Comments, quoting, and inline sequences are preserved, and nodes in Infrahub-reserved namespaces are left unchanged.

Preview the result before writing it, or verify that files are already formatted:

infrahubctl schema format schemas/ --diff   # preview the changes, write nothing
infrahubctl schema format schemas/ --check  # exit non-zero if any file would change

--check lets you run the formatter in a pre-commit hook or CI step.

Three opt-in flags apply further changes and can be combined:

  • --strip-defaults removes keys whose value matches the schema default.
  • --sort-by-order-weight orders attributes and relationships by their order_weight.
  • --backfill-order-weight sets order_weight on entries that do not define one.

For the full list of options, see the infrahubctl schema reference.

Check a schema​

During development, you can validate a schema file and preview the changes it would apply:

infrahubctl schema check <path to schema file or a directory> [--branch <branch_name>]

The check command returns a summary of the changes that would be applied if the schema were loaded. No changes are made to the database.

Load a schema file​

Schema files can be loaded into Infrahub with the infrahubctl command or directly via the Git integration.

info

Use infrahubctl for development and testing. The git integration option is better suited for production.

The infrahubctl command can be used to load individual schema files or multiple files as part of a directory.

infrahubctl schema load <path to schema file or a directory> <path to schema file or a directory> [--branch <branch_name>]
info

The infrahubctl schema load command can be used to both upload a new schema and update an existing one.

Troubleshooting​

Input should be a valid string (string_type)​

When loading a schema, you may encounter the error "Input should be a valid string (string_type)". This typically occurs when YAML interprets certain unquoted values as booleans instead of strings.

YAML automatically converts unquoted on, off, yes, no, true, and false values to boolean types. When these values appear in fields expecting strings (like choice names), schema validation fails.

Example of the problem:

---
version: "1.0"
nodes:
  - name: Stuff
    namespace: Random
    attributes:
      - name: status
        kind: Dropdown
        choices:
          - name: on  # Interpreted as boolean true
            label: On
          - name: off  # Interpreted as boolean false
            label: Off

Solution:

Quote all boolean-like string values in your schema:

---
version: "1.0"
nodes:
  - name: Stuff
    namespace: Random
    attributes:
      - name: status
        kind: Dropdown
        choices:
          - name: "on"  # Properly interpreted as string
            label: "On"
          - name: "off"
            label: "Off"

This issue commonly appears in:

  • Dropdown choice names
  • Attribute names