infrahub-jsonschema

Infrahub JSON Schema is the home of various JSON Schema files related to Infrahub

A JSON Schema file is a standard specification that describes the structure and validation rules for various data (YAML, JSON). It provides a way to define what a valid document should look like, including the types of values, required fields, default values, and other constraints.

Currently we maintain JSON Schema files for:

• Infrahub Schema definition file Schema file for Infrahub, usually defined in Yaml
• Infrahub Menu Schema Schema for defining menu structures in Infrahub im Yaml.
• Infrahub repository configuration file (.infrahub.yml)

Integration with standard IDE via yaml-language-server

In most IDE it's be possible to get inline format validation of a YAML file by providing the address of a JSON Schema file at the top of the file, using the syntax below

For schema definitions, use:

# yaml-language-server: $schema=https://schema.infrahub.app/infrahub/schema/latest.json
---
version: '1.0'

For menu definitions, use:

# yaml-language-server: $schema=https://schema.infrahub.app/infrahub/menu/latest.json
---
apiVersion: infrahub.app/v1
kind: Menu

Public URL

Everything under the schemas/ directory is automatically published to https://schema.infrahub.app to simplify the integration with external tools that requires a public URL

Validation

This repository includes automated validation to ensure all JSON files are valid JSON schemas and any .infrahub.yml files conform to the repository configuration schema.

Running Validation Locally

To validate all schema files locally:

uv run pytest test_schema_validation.py -v

This will:

• Validate that all .json files contain valid JSON and are valid JSON schemas
• Validate that any .infrahub.yml files are valid YAML and conform to the repository config schema
• Report any validation errors with detailed error messages

Continuous Integration

The validation runs automatically on every push and pull request via GitHub Actions. The CI workflow:

• Validates all JSON schema files using pytest
• Double-checks JSON syntax using jq
• Fails the build if any validation errors are found

How to update a Schema

Generate the new schemas, using the invoke tool from the main Infrahub repository.

invoke schema.generate-jsonschema

The command will create files under ./generated that needs to be copied to the corresponding location within this repository. The latest develop.json files can be copied as is and for released versions you would name them as [release-number].json and update the symlink to latest.json for the given schema.

Example:

• Copy the schema file to schemas/infrahub/schema/[version-number].json (i.e. 0.12.0.json)
• Navigate to the schemas/infrahub/schema and update the symbolic link

cd schemas/infrahub/schema
ln -f -s 0.12.0.json latest.json

After updating schemas, run the validation to ensure they are correct:

uv run pytest test_schema_validation.py -v