Skip to main content

Schema Validation and YAML Intelligence

This document explores how the Infrahub VSCode extension provides intelligent YAML editing capabilities, real-time schema validation, and navigation features that enhance the developer experience when working with infrastructure schemas.

Overview

Schema validation and YAML intelligence are fundamental features that transform VSCode into a powerful Infrahub development environment. These capabilities help catch errors early, provide contextual assistance, and accelerate schema development through intelligent code completion and navigation.

The Role of Schemas in Infrahub

Infrastructure as Schema

In Infrahub, schemas define the structure of your infrastructure data:

version: '1.0'
nodes:
- name: Device
namespace: Network
attributes:
- name: hostname
kind: Text
unique: true

This schema-first approach means:

  • Type Safety: Data must conform to defined structures
  • Consistency: All infrastructure follows the same patterns
  • Validation: Invalid data is rejected before it causes issues
  • Documentation: Schemas serve as living documentation

Why Validation Matters

Schema validation prevents several categories of errors:

  1. Syntax Errors: Malformed YAML that won't parse
  2. Type Mismatches: Wrong data types for attributes
  3. Constraint Violations: Breaking uniqueness or required fields
  4. Relationship Errors: Invalid references between objects
  5. Version Conflicts: Incompatible schema versions

How Schema Validation Works

Validation Pipeline

The extension implements a multi-stage validation pipeline:

File Change → YAML Parse → Schema Load → Validation → Diagnostics
↓ ↓ ↓ ↓ ↓
Detected Structure Reference Rules Display
Checking Resolution Applied Errors

Real-Time Validation

Validation occurs at multiple points:

  1. On Type: Incremental validation as you type (debounced)
  2. On Save: Full validation when file is saved
  3. On Open: Initial validation when file is opened
  4. On Focus: Re-validation when switching between files

Validation Scope

The extension validates files based on location:

# Automatically validated directories
models/ # Infrastructure models
schemas/ # Schema definitions

These directories are configured through:

{
"infrahub-vscode.schemaDirectory": "schemas"
}

YAML Intelligence Features

Syntax Highlighting

The extension provides enhanced syntax highlighting for Infrahub-specific constructs:

  • Keywords: version, nodes, attributes, relationships
  • Types: Text, Number, Boolean, IPHost, IPNetwork
  • Modifiers: unique, optional, default_value

Auto-Completion

Context-aware suggestions appear as you type:

nodes:
- name: Router
attributes:
- name: hostname
kind: | # Cursor here triggers type suggestions
# Text, Number, Boolean, IPHost, etc.

Go-to-Definition

Navigate between related schemas with F12 or Ctrl+Click:

relationships:
- name: interfaces
peer: NetworkInterface # Ctrl+Click jumps to NetworkInterface definition
kind: Component

Document Symbols

The outline view shows schema structure:

📄 network.yml
└─ nodes
└─ Device
├─ attributes
│ ├─ hostname
│ └─ model
└─ relationships
└─ interfaces

Schema Validation Rules

Structural Validation

The extension enforces schema structure:

# Valid structure
version: '1.0'
nodes:
- name: Device
namespace: Network

# Invalid - missing version
nodes: # ❌ Error: Schema must include version
- name: Device

Attribute Validation

Attributes must follow specific rules:

attributes:
- name: hostname
kind: Text # ✅ Valid kind
unique: true # ✅ Valid modifier

- name: port
kind: String # ❌ Error: Invalid kind 'String', use 'Text'

- name: ip_address
kind: IPHost
mandatory: true # ❌ Error: Use 'optional: false' instead

Relationship Validation

Relationships are validated for consistency:

relationships:
- name: location
peer: LocationSite # Must reference existing node
kind: Parent # Must be valid relationship kind
cardinality: one # Must be valid cardinality

- name: interfaces
peer: NonExistent # ❌ Error: Node 'NonExistent' not found
kind: Invalid # ❌ Error: Invalid relationship kind

Understanding Validation Messages

Error Categories

Validation produces different message types:

  1. Errors (Red): Must be fixed before schema works

    • Missing required fields
    • Invalid types
    • Syntax errors
  2. Warnings (Yellow): Should be addressed but won't break functionality

    • Deprecated patterns
    • Performance concerns
    • Best practice violations
  3. Information (Blue): Helpful suggestions

    • Optimization opportunities
    • Alternative approaches
    • Documentation hints

Message Structure

Each validation message contains:

[Severity] [Location] Message
Example: Error at line 15: Attribute kind 'String' is not valid

Common Validation Errors

Missing Required Fields

nodes:
- namespace: Network # ❌ Error: Missing required field 'name'

Solution: Add the missing field:

nodes:
- name: Device
namespace: Network

Invalid Attribute Kind

attributes:
- name: count
kind: Integer # ❌ Error: Use 'Number' instead of 'Integer'

Solution: Use correct type:

attributes:
- name: count
kind: Number

Circular Dependencies

nodes:
- name: A
relationships:
- peer: B
kind: Parent
- name: B
relationships:
- peer: A
kind: Parent # ❌ Error: Circular dependency detected

Solution: Redesign relationship hierarchy

Advanced Validation Concepts

Schema Inheritance

Understanding how schemas inherit from base definitions:

nodes:
- name: Device
namespace: Network
inherit_from:
- BuiltinDevice # Inherits attributes and relationships
attributes:
- name: custom_field # Adds to inherited attributes
kind: Text

The validator checks:

  • Base schema exists
  • No attribute conflicts
  • Relationship compatibility

Cross-File Validation

The extension validates references across files:

# File: schemas/network.yml
nodes:
- name: Device
namespace: Network

# File: schemas/interface.yml
nodes:
- name: Interface
namespace: Network
relationships:
- name: device
peer: NetworkDevice # Validated across files

Version Compatibility

Schema versions affect validation rules:

version: '1.0'  # Original schema format

version: '1.1' # Supports additional features
generics: # New in 1.1
- name: GenericDevice

Performance Considerations

Incremental Validation

The extension uses incremental validation for performance:

  1. Parse Caching: YAML AST cached between edits
  2. Partial Updates: Only changed sections re-validated
  3. Debouncing: Validation delayed during rapid typing
  4. Background Processing: Validation doesn't block UI

Large File Handling

For large schema files:

  • Lazy Loading: Schemas loaded on-demand
  • Chunked Processing: Large files processed in segments
  • Priority Validation: Visible content validated first
  • Throttling: Rate-limited validation for huge files

Customizing Validation

Validation Settings

Configure validation behavior:

{
"yaml.schemas": {
"https://schema.infrahub.app/infrahub/schema/latest.json": [
"schemas/**/*.yml",
"models/**/*.yaml"
]
},
"yaml.validate": true,
"yaml.customTags": [
"!include",
"!secret"
]
}

Disabling Validation

To temporarily disable validation:

  1. Per File: Add comment at top

    # yaml-language-server: $schema=none
  2. Per Workspace: Modify settings

    {
    "yaml.validate": false
    }

Integration with Other Tools

YAML Language Server

The extension leverages the Red Hat YAML extension:

  • Schema Association: Links files to Infrahub schemas
  • JSON Schema: Uses JSON Schema for validation
  • Custom Tags: Supports Infrahub-specific tags

Linting Integration

Works alongside linting tools:

  • yamllint: Style and formatting checks
  • Prettier: Code formatting
  • Vale: Documentation linting

Troubleshooting Validation Issues

Validation Not Working

If validation isn't functioning:

  1. Check File Location: Ensure file is in configured directory
  2. Verify Extension: Confirm YAML extension is installed
  3. Schema Association: Check schema URL is correct
  4. Reload Window: Try reloading VSCode

False Positives

If seeing incorrect errors:

  1. Update Extension: Ensure latest version
  2. Check Schema Version: Verify schema compatibility
  3. Clear Cache: Reload VSCode window
  4. Report Issue: File bug report if persistent

Performance Issues

If validation is slow:

  1. File Size: Consider splitting large files
  2. Disable Real-time: Turn off on-type validation
  3. Increase Debounce: Adjust validation delay
  4. Check Extensions: Disable conflicting extensions

Further Reading