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.

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