YAML Schema Reference¶
STRUCT provides JSON schema validation to ensure your YAML configuration files are correctly structured. This helps catch errors early and provides IDE support with autocompletion.
Schema Location¶
The official schema is available at:
IDE Configuration¶
VS Code¶
- Install the YAML extension
- Add this to your workspace settings (
.vscode/settings.json
):
{
"yaml.schemas": {
"https://raw.githubusercontent.com/httpdss/struct/main/struct-schema.json": ".struct.yaml"
}
}
This provides validation and autocompletion for all .struct.yaml
files.
JetBrains IDEs (IntelliJ, PyCharm, etc.)¶
- Go to Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings
- Click + to add a new mapping
- Set Schema file or URL to:
https://raw.githubusercontent.com/httpdss/struct/main/struct-schema.json
- Set File path pattern to:
*.struct.yaml
Generating Custom Schema¶
If you have custom structures, generate a schema that includes them:
# Generate schema with custom structures
struct generate-schema -s /path/to/custom/structures -o my-schema.json
# Use in VS Code settings
{
"yaml.schemas": {
"./my-schema.json": ".struct.yaml"
}
}
Schema Structure¶
The schema validates the following top-level properties:
files
(array)¶
Defines files to be created:
files:
- filename.txt:
content: "File contents"
permissions: "0644"
skip: false
skip_if_exists: false
file: "https://example.com/template.txt"
Properties:
content
(string): Inline file contentpermissions
(string): Octal permissions (e.g., "0755")skip
(boolean): Skip file creationskip_if_exists
(boolean): Skip if file existsfile
(string): External file URL or path
folders
(array)¶
Defines folders and nested structures:
Properties:
struct
(string|array): Structure name(s) to applywith
(object): Variables to pass to the structure
variables
(array)¶
Defines template variables:
variables:
- variable_name:
description: "Variable description"
type: "string"
default: "default_value"
Properties:
description
(string): Human-readable descriptiontype
(string): Variable type (string, integer, boolean)default
(any): Default value
pre_hooks
(array)¶
Shell commands to run before generation:
post_hooks
(array)¶
Shell commands to run after generation:
Validation¶
Command Line Validation¶
Programmatic Validation¶
import json
import yaml
from jsonschema import validate
# Load schema
with open('struct-schema.json') as f:
schema = json.load(f)
# Load and validate config
with open('my-config.yaml') as f:
config = yaml.safe_load(f)
validate(config, schema) # Raises exception if invalid
Common Validation Errors¶
Invalid File Structure¶
# ❌ Wrong - files should be array of objects
files:
README.md: "content"
# ✅ Correct
files:
- README.md:
content: "content"
Missing Required Properties¶
# ❌ Wrong - struct property missing
folders:
- src/:
with:
name: "myapp"
# ✅ Correct
folders:
- src/:
struct: "project/node"
with:
name: "myapp"
Invalid Variable Types¶
# ❌ Wrong - type should be string
variables:
- port:
type: number
default: 8080
# ✅ Correct
variables:
- port:
type: integer
default: 8080
Schema Extensions¶
You can extend the base schema for custom validation:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"allOf": [
{
"$ref": "https://raw.githubusercontent.com/httpdss/struct/main/struct-schema.json"
},
{
"properties": {
"custom_section": {
"type": "object",
"properties": {
"custom_property": {"type": "string"}
}
}
}
}
]
}
IDE Benefits¶
With schema validation enabled, you get:
- Real-time validation: Errors highlighted as you type
- Autocompletion: Suggested properties and values
- Documentation: Hover tooltips with property descriptions
- Structure guidance: Valid structure names and paths
Troubleshooting¶
Schema Not Loading¶
- Check internet connection (for remote schema)
- Verify file path (for local schema)
- Restart IDE after configuration changes
- Check IDE logs for error messages
Validation Errors¶
- Use
struct validate
command for detailed error messages - Check schema documentation for required properties
- Verify YAML syntax is correct
- Ensure structure names exist in your installation
Performance Issues¶
- Use local schema files for better performance
- Consider schema caching in your IDE
- Limit schema complexity for large configurations
This schema system ensures your STRUCT configurations are valid and provides a better development experience through IDE integration.