Skip to main content

​
Overview

Once you’ve created your schema files, you need to import them into Infrahub. This guide covers multiple methods for loading schemas and managing schema updates.

​
Prerequisites

Before importing:
  • Infrahub server must be running
  • Schema files must be valid YAML
  • You need appropriate access credentials

​
Import Methods

​
Using the Python SDK

1

Install the SDK

pip install infrahub-sdk
2

Create a client connection

from infrahub_sdk import InfrahubClient

# Connect to Infrahub
client = InfrahubClient(
    address="http://localhost:8000",
    username="admin",
    password="infrahub"
)
3

Load the schema

# Load schema from a file
result = await client.schema.load(
    schemas=["path/to/schema.yml"]
)

if result.schema_updated:
    print("Schema updated successfully")
else:
    print("Schema unchanged (idempotent load)")

​
Using the REST API

curl -X POST "http://localhost:8000/api/schema/load" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "schemas": [
      {
        "version": "1.0",
        "nodes": [...]
      }
    ]
  }'

​
Using infrahubctl CLI

1

Install infrahubctl

pip install infrahub-sdk
2

Load schema files

# Load a single schema file
infrahubctl schema load schema.yml

# Load multiple schema files
infrahubctl schema load schema1.yml schema2.yml

# Load all schemas from a directory
infrahubctl schema load models/*.yml

​
Loading Multiple Schemas

You can load multiple related schemas in a single operation: 
from infrahub_sdk import InfrahubClient

client = InfrahubClient(address="http://localhost:8000")

# Load multiple schema files
result = await client.schema.load(schemas=[
    "models/organization.yml",
    "models/location.yml",
    "models/device.yml",
    "models/network.yml"
])

print(f"Schemas updated: {result.schema_updated}")
Load order matters when schemas have dependencies. Ensure that referenced schemas (e.g., parent nodes) are loaded before schemas that reference them.

​
Branch-Specific Schema Loading

Schemas can be loaded into specific branches for testing before merging to main: 
from infrahub_sdk import InfrahubClient

client = InfrahubClient(address="http://localhost:8000")

# Create a new branch
branch = await client.branch.create(
    branch_name="schema-update",
    description="Testing new schema changes"
)

# Load schema into the branch
result = await client.schema.load(
    schemas=["models/updated-schema.yml"],
    branch="schema-update"
)

if result.schema_updated:
    print("Schema loaded into branch 'schema-update'")

​
Schema Update Behavior

​
Idempotent Loading

Loading the same schema multiple times is idempotent - no changes occur if the schema hasn’t changed: 
# First load - creates schema
result1 = await client.schema.load(schemas=["schema.yml"])
print(result1.schema_updated)  # True

# Second load - no changes
result2 = await client.schema.load(schemas=["schema.yml"])
print(result2.schema_updated)  # False

​
Schema Migration

When you update an existing schema, Infrahub automatically:
  1. Validates the changes against existing data
  2. Migrates existing objects to match the new schema
  3. Updates node metadata (timestamps, etc.)
  4. Applies default values to new attributes
# Original schema has 'name' and 'description'
# Updated schema adds 'location' attribute

result = await client.schema.load(schemas=["updated-schema.yml"])

if result.schema_updated:
    print("Schema migrated successfully")
    # Existing objects now have 'location' attribute with null/default values

​
Verifying Schema Import

1

Check schema in UI

Navigate to Schema in the Infrahub web interface to view loaded schemas.
2

Query schema via API

from infrahub_sdk import InfrahubClient

client = InfrahubClient(address="http://localhost:8000")

# Get a specific schema
device_schema = await client.schema.get(kind="InfraDevice")

print(f"Schema: {device_schema.name}")
print(f"Namespace: {device_schema.namespace}")
print(f"Attributes: {[a.name for a in device_schema.attributes]}")
print(f"Relationships: {[r.name for r in device_schema.relationships]}")
3

List all schemas

# Get all schemas
all_schemas = await client.schema.all()

for schema in all_schemas:
    print(f"{schema.namespace}.{schema.name}")

​
Handling Schema Conflicts

When schema changes conflict with existing data:
If you add a non-optional attribute to an existing schema:
attributes:
  - name: new_required_field
    kind: Text
    optional: false
    default_value: "default"  # Required for migration
Always provide a default_value when adding mandatory attributes to schemas with existing data.
Changing attribute kinds may fail if existing data is incompatible:
# Before: kind: Text
# After: kind: Number
You may need to:
  1. Export existing data
  2. Delete the attribute
  3. Re-create with new type
  4. Import converted data
Removing attributes from schema:
  • Data is not immediately deleted
  • Attribute becomes inaccessible via API
  • Use data migration tools to clean up if needed

​
Schema Load Response

The schema load operation returns detailed information: 
result = await client.schema.load(schemas=["schema.yml"])

print(f"Schema updated: {result.schema_updated}")
print(f"Diff: {result.diff}")
Response structure: 
{
  "schema_updated": true,
  "diff": {
    "added": ["NetworkDevice"],
    "removed": [],
    "changed": ["NetworkInterface"]
  }
}

​
Environment-Specific Loading

# Development environment
client = InfrahubClient(
    address="http://localhost:8000",
    username="admin",
    password="infrahub"
)

result = await client.schema.load(schemas=["schema.yml"])

​
Best Practices

Version Control

Keep schema files in Git to track changes and enable rollbacks

Test in Branches

Test schema changes in feature branches before merging to main

Validate Before Loading

Use YAML validators and schema linters before importing

Document Changes

Maintain a changelog for schema modifications

​
Troubleshooting

Problem: Schema fails to load with validation errorsSolution:
  • Check YAML syntax is valid
  • Ensure all required fields are present
  • Verify referenced schemas exist
  • Check for circular dependencies
Problem: Cannot connect to Infrahub serverSolution:
  • Verify server is running
  • Check network connectivity
  • Confirm credentials are correct
  • Verify API endpoint URL
Problem: Authentication or authorization failuresSolution:
  • Verify user has schema management permissions
  • Check API token is valid
  • Ensure user account is not locked

​
Next Steps

Create Schema

Learn how to define schemas in YAML

Schema Validation

Understand validation rules and constraints

Working with Branches

Manage schemas across branches

Python SDK

Explore the full SDK capabilities

Build docs developers (and LLMs) love

Get started for freeTalk to us