From 09f81361a19e26f1ca0603a15c612ceff4734e6a Mon Sep 17 00:00:00 2001 From: Pete Crocker Date: Thu, 30 Jul 2026 13:21:58 +0100 Subject: [PATCH] docs(schema): document `infrahubctl schema format` Add a "Format schema files" section to the Create and load schema page: default key-ordering behaviour, --diff / --check, and the opt-in --strip-defaults / --sort-by-order-weight / --backfill-order-weight flags. DO NOT MERGE until an infrahub-sdk release that ships `infrahubctl schema format` is published (feature merged in opsmill/infrahub-sdk-python#1189). Merging earlier would document a command absent from the released CLI. --- docs/docs/schema/create-and-load.mdx | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/docs/schema/create-and-load.mdx b/docs/docs/schema/create-and-load.mdx index 2f1b082c734..bcb3f370e7c 100644 --- a/docs/docs/schema/create-and-load.mdx +++ b/docs/docs/schema/create-and-load.mdx @@ -37,6 +37,33 @@ For a full reference of all available properties, see [Nodes & attributes](./nod 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. + +```shell +infrahubctl schema format +``` + +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: + +```shell +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`](./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]($(base_url)infrahubctl/infrahubctl-schema). + ## Check a schema During development, you can validate a schema file and preview the changes it would apply: