Publish with bricks.yaml
Publish blueprints using bricks.yaml for simplified syntax, auto-populated fields, multi-document support, and YAML-native features
bricks.yaml provides a slimmer, more maintainable alternative to bricks.json for defining blueprints. You only specify what you need to change; everything else is auto-populated from the package definitions.
Key advantages:
Simplified syntax: only specify what you need to change
Auto-populated fields: props and outputs inherited from packages
Multi-document support: publish multiple blueprints from one file
YAML features: anchors, aliases, and merge keys for reusable configuration
Higher priority: when both files exist, YAML takes precedence
Basic format
Minimal blueprint
name: web_application
version: 1.0.0
packages:
- name: terraform_aws_vpc
version: 3.0.0Required fields (for package-composition blueprints):
name: blueprint nameversion: blueprint version (semver)packages: non-empty list of packages (at least one)
All field names are lowercase. Blueprint-level fields include name, version, description, tags, inputs, packages, and outputs. Package-level fields include name, version, id, and props.
Complete blueprint
Package configuration
Auto-populated props
Props you don't specify are automatically wired to blueprint-level inputs, inheriting their type, description, and default value from the package definition.
When to specify props:
Override default values
Connect to other packages via data references
Use blueprint inputs
Set hardcoded values
Explicit package IDs
Specify the id field when using the same package multiple times, referencing package outputs in other packages, or ensuring predictable output references.
Without an explicit id, the package name is used as the ID. IDs must start with a letter or underscore and contain only letters, numbers, and underscores (^[a-zA-Z_][a-zA-Z0-9_]*$).
Auto-populated outputs
Package outputs are automatically included. You only need to specify outputs in the blueprint if you want to change output names or add additional outputs not in the package.
If you define an output with the same name as a package output, your definition takes priority for that name, and the original package output is included under <packageId>_<outputName>.
If you don't need to modify outputs, omit the outputs section entirely.
Value references
Data references
Reference outputs from other packages using data.<package_id>.<output_key>:
Use lowercase data, not Data. The YAML format uses lowercase references (data.*, inputs.*) while the JSON format uses capitalized references (Data.*, Props.*).
Data references create implicit dependencies. Bluebricks builds a DAG from these references and executes packages in the correct order. For details, see Parallel Execution.
Input references
Reference blueprint inputs using inputs.<input_key>:
String values
How values are interpreted:
Simple references (no quotes needed):
You don't need to quote plain strings. Bluebricks automatically wraps literal values during publishing to prevent expression parsing issues. Quoting is only needed if a value looks like an expression but you intend it as a literal:
Values containing inputs., data., or secrets. are treated as expressions and transformed. All other values are treated as string literals.
YAML features
Anchors and aliases
Define configuration once with anchors (&name) and reuse with aliases (*name):
Merge keys
Combine multiple configurations with merge keys (<<):
Anchors with package repetition
Use anchors when repeating the same package. When overriding props with anchors, you replace the entire props object. To merge props, use nested anchors:
Input configuration
Input types
Define blueprint inputs with types, defaults, and constraints. Supported types: string, number, bool, list, map, any.
Inputs without a default are required at deployment time. Inputs with a default are optional.
Allowed values
Restrict input values to specific options:
Multi-document YAML
Publish multiple blueprints from a single file using document separators (---):
Each document is published as a separate blueprint.
Publishing
Publish your blueprint using the standard command:
When both bricks.yaml and bricks.json exist, YAML takes precedence. The CLI will warn: Both bricks.json and bricks.yaml found. Using bricks.yaml (higher priority).
Multi-document publishing
Validation during publish
The CLI and backend validate your blueprint during publish. This includes schema checks, output reference validation against child blueprints, and case-sensitivity enforcement.
blueprint 1: missing 'version' property
Missing required field
Couldn't resolve package <name>@<version>
Package or version not found
Output key "<key>" not found in package <name>@<version>
Invalid output reference
failed to parse bricks.yaml: failed to decode blueprint 1: yaml: line 15: did not find expected key
Malformed YAML
Property "bricks_depnds" is not a recognized reserved property. Did you mean 'bricks_depends'?
Typo in reserved bricks_ property
Blueprint has child packages not referenced in any output
Every child package must appear in at least one output via Data.<packageId>.<outputName>
Blueprint validation failed... The following output references are invalid
Referenced output does not exist in the child blueprint
Blueprint property/output contains invalid lowercase references
Used data. or props. instead of Data. or Props. in bricks.json
Property names starting with bricks_ are reserved. The only currently supported reserved property is bricks_depends. If you use an unrecognized bricks_ property, publishing fails with an error and a suggestion for the closest valid name.
Bluebricks validates that every Data.<packageId>.<outputName> reference in your blueprint points to an output that exists in the child blueprint. If a child blueprint does not define the referenced output, publishing fails with a list of invalid references and the available outputs for each child.
Development workflow
Finding packages
Search for packages to add to your blueprint:
Inspecting package details
Get package information before adding to your blueprint:
Building your YAML
Use the information from bricks blueprint describe to construct your blueprint:
Search and identify packages:
bricks blueprint search -q "vpc"Get package details:
bricks blueprint describe terraform_aws_vpcCreate
bricks.yamlwith only the props you need to overrideVerify references: use
bricks blueprint get outsto confirm output keys exist before referencing them
Iterative development
Build your blueprint incrementally:
Viewing generated blueprint
After publishing, view the full hydrated blueprint with all auto-populated props and outputs:
This shows all props (including defaults from packages), all outputs, generated IDs, and full resolution of inputs and data references.
Migration from bricks.json
You don't need to migrate all blueprints at once:
Keep existing
bricks.jsonfiles workingCreate new blueprints with
bricks.yamlMigrate gradually as you update blueprints
If you already have a published blueprint, export it as JSON to use as a reference when writing your YAML:
This shows all props, outputs, and resolved references, so you know exactly which fields to include or override.
To convert an existing blueprint:
Create a new
bricks.yamlfileCopy name, version, description, tags
Define inputs from props
List packages (only override props as needed)
Add outputs only if customizing
Test with
bricks blueprint publish
bricks.yaml is converted to bricks.json server-side. View the generated result with:
See also
Creating Blueprints: step-by-step guide for the UI wizard and CLI
Blueprint Composition Patterns: architectural patterns and dependency strategies
Using expr: expression language for dynamic configuration
Last updated
Was this helpful?

