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:
- Syntax Errors: Malformed YAML that won't parse
- Type Mismatches: Wrong data types for attributes
- Constraint Violations: Breaking uniqueness or required fields
- Relationship Errors: Invalid references between objects
- 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:
- On Type: Incremental validation as you type (debounced)
- On Save: Full validation when file is saved
- On Open: Initial validation when file is opened
- 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:
-
Errors (Red): Must be fixed before schema works
- Missing required fields
- Invalid types
- Syntax errors
-
Warnings (Yellow): Should be addressed but won't break functionality
- Deprecated patterns
- Performance concerns
- Best practice violations
-
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:
- Parse Caching: YAML AST cached between edits
- Partial Updates: Only changed sections re-validated
- Debouncing: Validation delayed during rapid typing
- 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:
-
Per File: Add comment at top
# yaml-language-server: $schema=none
-
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:
- Check File Location: Ensure file is in configured directory
- Verify Extension: Confirm YAML extension is installed
- Schema Association: Check schema URL is correct
- Reload Window: Try reloading VSCode
False Positives
If seeing incorrect errors:
- Update Extension: Ensure latest version
- Check Schema Version: Verify schema compatibility
- Clear Cache: Reload VSCode window
- Report Issue: File bug report if persistent
Performance Issues
If validation is slow:
- File Size: Consider splitting large files
- Disable Real-time: Turn off on-type validation
- Increase Debounce: Adjust validation delay
- Check Extensions: Disable conflicting extensions