Blueprint Validate Command
Essential knowledge
Intended Audience:
Technical User
Author:
Marco Heuer
Changed on:
20 Aug 2026
Overview
Master the`blueprint validate` command to perform multi-layered health checks on manifests before deployment. Implementing partners learn to verify structural integrity, business rules, and path accessibility, ensuring error-free "recipes."This provides a business safety net, preventing broken installs and reducing downtime by catching invalid versions or conflicting filters early. Note: Validation is mandatory; the CLI blocks installations if rules (such as requiring exact semantic versions) are violated.Key points
- Function:
`blueprint validate`performs a pre-installation health check on structural, business, and path rules. - Three Layers: It verifies JSON schema, logical rules (like unique module names), and path/URL accessibility (S3/HTTPS/Local).
- Error Collection: Reports all errors in a single run, allowing you to fix multiple issues simultaneously.
- Key Constraints: * At least one author is required.
- Module versions must be exact (no ranges like
`^`or`~`). - Modules cannot have both
`includes`and`excludes`filters.
- Module versions must be exact (no ranges like
- Benefit: Catches bugs early without side effects on the account.
The
Output:
Blueprint validation successful!
All checks passed:
- Business rules validated
- Module paths verified
- Semantic versions validated
- Structure validated
Output:
Blueprint validation failed!
Found 1 error:
Error 1: [RULE_005]
Message: Invalid semver constraint for module 'core': xyz
Field: modules[core].version
Value: xyz
Tip: Fix the errors above and run validation again.
Output:
Blueprint validation failed!
Found 5 errors:
Error 1: [RULE_001]
Message: Blueprint validation failed: must have at least one author in the "authors" array
Field: authors
Error 2: [RULE_002]
Message: Blueprint validation failed: module "core" cannot have both "includes" and "excludes"
Field: modules[core].includes/excludes
Error 3: [RULE_003]
Message: Blueprint validation failed: module "order" appears multiple times (module names must be unique)
Field: modules
Value: order
Error 4: [RULE_007]
Message: Module 'inventory' version must be exact (not a constraint): ^2.0.0
Field: modules[inventory].version
Value: ^2.0.0
Error 5: [RULE_007]
Message: Module 'fulfilment' version must be exact (not a constraint): ~1.5.0
Field: modules[fulfilment].version
Value: ~1.5.0
Tip: Fix the errors above and run validation again.
Note: All errors are reported in a single validation run, allowing you to fix all issues at once.
Output:
Fix: Ensure all required fields are present and non-empty:
"name": "my-blueprint",
"version": "1.0.0",
"description": "My custom blueprint",
"created": "2024-01-01T00:00:00.000Z",
"modules": [...]
}
Fix: Use exact semantic versions (e.g.,
Fix: Replace version ranges (
Fix: Choose either
Fix: Add at least one author to the blueprint:
{
"name": "Your Name",
"email": "your.email@example.com"
}
]
Fix:
Fix: Provide complete S3 URL with bucket and key:
`blueprint validate` command validates a blueprint file against business rules, structural requirements, and semantic versioning constraints. It performs comprehensive validation before installation to catch errors early.Syntax
`fluent blueprint validate <blueprint>`Arguments
| Argument | Description | Required |
`<blueprint>` | Path to the blueprint JSON file | Yes |
Options
None. This command operates without additional options.Validation Layers
The validate command performs three layers of validation:1. Structural Validation
Validates required fields and data types:- SCHEMA_001: Required fields must be present and non-empty (name, version, description, created, modules)
- SCHEMA_002: Fields must have correct data types (e.g., modules must be an array)
- JSON format validity
2. Business Rule Validation
Validates logical constraints:- RULE_001: At least one author required
- RULE_002: Module cannot have both includes AND excludes
- RULE_003: Module names must be unique
- RULE_004: Glob patterns must be valid
- RULE_005: Semantic version constraints must be valid
- RULE_006: Conflict version constraints must be valid
- RULE_007: Module versions must be exact (not ranges), or "latest"
3. ModulePath Validation
Validates file paths and URLs:- PATH_001: Local path exists and is readable
- PATH_002: Local path is accessible
- PATH_003: URL is well-formed
- PATH_004: Protocol is supported (https/s3)
- PATH_006: Path format is valid
- PATH_007: Path is not empty
- PATH_008: S3 URL has bucket name
- PATH_009: S3 URL has key path
Exit Codes
| Code | Meaning |
| 0 | Validation successful |
| 1 | Validation failed or file not found |
Examples
Successful Validation
`fluent blueprint validate retail-accelerator-1.0.0.json`Output:
`Validating blueprint: retail-accelerator v1.0.0`Blueprint validation successful!
All checks passed:
- Business rules validated
- Module paths verified
- Semantic versions validated
- Structure validated
Failed Validation (Single Error)
`fluent blueprint validate invalid-blueprint.json`Output:
`Validating blueprint: invalid-blueprint v1.0.0`Blueprint validation failed!
Found 1 error:
Error 1: [RULE_005]
Message: Invalid semver constraint for module 'core': xyz
Field: modules[core].version
Value: xyz
Tip: Fix the errors above and run validation again.
Failed Validation (Multiple Errors)
`fluent blueprint validate many-issues.json`Output:
`Validating blueprint: many-issues v1.0.0`Blueprint validation failed!
Found 5 errors:
Error 1: [RULE_001]
Message: Blueprint validation failed: must have at least one author in the "authors" array
Field: authors
Error 2: [RULE_002]
Message: Blueprint validation failed: module "core" cannot have both "includes" and "excludes"
Field: modules[core].includes/excludes
Error 3: [RULE_003]
Message: Blueprint validation failed: module "order" appears multiple times (module names must be unique)
Field: modules
Value: order
Error 4: [RULE_007]
Message: Module 'inventory' version must be exact (not a constraint): ^2.0.0
Field: modules[inventory].version
Value: ^2.0.0
Error 5: [RULE_007]
Message: Module 'fulfilment' version must be exact (not a constraint): ~1.5.0
Field: modules[fulfilment].version
Value: ~1.5.0
Tip: Fix the errors above and run validation again.
Note: All errors are reported in a single validation run, allowing you to fix all issues at once.
File Not Found
`fluent blueprint validate missing.json`Output:
`Blueprint file not found: missing.json`Common Validation Errors
1. Missing Required Fields
Error:`Blueprint validation failed: missing required field "name"`Fix: Ensure all required fields are present and non-empty:
`name`: Blueprint name`version`: Blueprint version`description`: Blueprint description`created`: Creation date (ISO 8601 format)`modules`: Array of module definitions
`{`"name": "my-blueprint",
"version": "1.0.0",
"description": "My custom blueprint",
"created": "2024-01-01T00:00:00.000Z",
"modules": [...]
}
2. Invalid Semantic Versions
Error:`Invalid semver constraint for module 'core': xyz`Fix: Use exact semantic versions (e.g.,
`1.0.0`, `2.1.3`) or `latest`.3. Version Ranges Not Allowed
Error:`Module 'order' version must be exact (not a constraint): ^2.0.0`Fix: Replace version ranges (
`^2.0.0`, `~1.5.0`) with exact versions (`2.0.0`, `1.5.0`) or `latest`.4. Both Includes and Excludes
Error:`Module 'core' cannot have both includes and excludes`Fix: Choose either
`includes` or `excludes` for each module, not both.5. Missing Authors
Error:`Authors array is required`Fix: Add at least one author to the blueprint:
`"authors": [`{
"name": "Your Name",
"email": "your.email@example.com"
}
]
6. Invalid Module Path
Error:`Local path does not exist: /path/to/module`Fix:
- Verify the path exists
- Use absolute or relative paths
- Ensure file/directory is readable
- For local development, use tilde (
`~`) for home directory
7. Invalid S3 URL
Error:`S3 URL must include bucket name: s3://`Fix: Provide complete S3 URL with bucket and key:
`s3://bucket-name/path/to/module.zip`Integration with other Commands
Typical Workflow
`# 1. Create blueprint template
`fluent blueprint create --name retail-accelerator`# 2. Edit the generated file
# ... customise blueprint ...
``# 3. Validate before installation
`fluent blueprint validate retail-accelerator-1.0.0.json`# 4. Install if validation passes
`fluent blueprint install retail-accelerator-1.0.0.jsonPre-Installation Check
The`blueprint install` command automatically validates blueprints before installation, but running `validate` assists in: - Catching errors early
- Testing blueprints without side effects
- Verifying blueprint files before committing to version control
Best Practices
- Validate Early: Run validation after creating or modifying blueprints
- Version Control: Commit only validated blueprints
- CI/CD Integration: Add validation to your build pipeline
- Test Locally: Validate with local modulePaths before using remote URLs
- Fix All Issues: Review all reported errors and fix them together for efficiency
Technical Details
Validation Order
- Check file exists
- Load and parse JSON
- Validate business rules (collects all errors)
- Validate module paths (collects all errors, skipped if critical schema errors exist)
Error Collection Behaviour
Validation collects and reports all errors in a single run, allowing you to:- See all issues at once
- Fix multiple problems before re-validating
- Get a comprehensive view of what needs attention
- Required fields: All missing fields reported together
- Business rules: All rule violations across all modules collected
- Module paths: All path errors collected (unless critical schema errors prevent it)
- Critical errors: If required fields are missing or modules is not an array, path validation is skipped (can't validate further)
Troubleshooting
"Blueprint file not found"
Cause: File path is incorrect or file doesn't existSolution:- Check file name and extension (must be
`.json`) - Verify file path (relative or absolute)
- Use
`ls`to confirm file exists
"Failed to parse blueprint"
Cause: JSON syntax error in blueprint fileSolution:- Validate JSON syntax using a JSON validator
- Check for trailing commas, missing quotes, or brackets
- Use a JSON formatter to identify syntax issues
"Invalid server constraint"
Cause: Module version doesn't follow semantic versioningSolution:- Use format:
`MAJOR.MINOR.PATCH`(e.g.,`1.0.0`) - Or use keyword:
`latest` - Remove version ranges:
`^`,`~`,`>`,`<`, etc.
"Module path validation failed"
Cause: File path or URL is invalid or inaccessibleSolution:- Local paths: Verify file/directory exists and is readable
- HTTP URLs: Check URL format and accessibility
- S3 URLs: Verify bucket exists and credentials are configured - Use
`~`prefix for home directory paths
Related Commands
- Blueprint Create - Create blueprint templates
- Blueprint Install - Install validated blueprints
- Blueprint Describe - View blueprint details
