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.0

Required fields (for package-composition blueprints):

• name: blueprint name

• version: 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

name: web_infrastructure
version: 1.0.0
description: Web application infrastructure on AWS
tags:
  - aws
  - production

inputs:
  region:
    type: string
    default: us-east-1
    description: AWS region
  vpc_cidr:
    type: string
    default: 10.0.0.0/16

packages:
  - id: network
    name: terraform_aws_vpc
    version: 3.0.0
    props:
      cidr_block: inputs.vpc_cidr
      region: inputs.region

  - id: database
    name: terraform_aws_rds
    version: 2.1.0
    props:
      vpc_id: data.network.vpc_id
      subnet_ids: data.network.private_subnet_ids

outputs:
  vpc_id:
    value: data.network.vpc_id
    description: VPC identifier
  db_endpoint:
    value: data.database.endpoint
    description: Database endpoint

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.

packages:
  - name: terraform_aws_s3
    version: 2.5.0
    props:
      region: inputs.region
      # All other props (bucket_name, encryption, etc.)
      # are auto-wired to blueprint inputs 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.

packages:
  - id: api_lambda
    name: terraform_aws_lambda
    version: 1.4.0
    props:
      function_name: api-handler

  - id: worker_lambda
    name: terraform_aws_lambda
    version: 1.4.0
    props:
      function_name: worker-handler

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.

outputs:
  vpc_id:
    value: data.network.vpc_id
    description: VPC identifier

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>:

packages:
  - id: vpc
    name: terraform_aws_vpc
    version: 3.0.0

  - id: subnet
    name: terraform_aws_subnet
    version: 2.0.0
    props:
      vpc_id: data.vpc.vpc_id
      availability_zone: data.vpc.availability_zones

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>:

inputs:
  environment:
    type: string
    default: dev
  region:
    type: string
    default: us-east-1

packages:
  - name: terraform_aws_s3
    version: 2.5.0
    props:
      bucket_name: inputs.environment
      region: inputs.region

String values

How values are interpreted:

Simple references (no quotes needed):

props:
  vpc_id: data.vpc.vpc_id          # Data reference
  region: inputs.region             # Input reference
  function_name: execute            # Plain string

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:

props:
  function_name: execute-api         # Auto-quoted during publish
  bucket_name: my-app-logs           # Auto-quoted during publish
  literal_ref: 'data.not_a_ref'     # Force literal with quotes

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):

name: shared_configuration
version: 1.0.0

common_settings: &defaults
  region: us-east-1
  timeout: 300
  retries: 3

packages:
  - name: terraform_aws_s3
    version: 2.5.0
    props:
      <<: *defaults
      bucket_name: application-data

  - name: terraform_aws_dynamodb
    version: 1.8.0
    props:
      <<: *defaults
      table_name: application-state

Merge keys

Combine multiple configurations with merge keys (<<):

name: merged_settings
version: 1.0.0

base_config: &base
  timeout: 300
  retries: 3

monitoring_config: &monitoring
  logging_enabled: true
  metrics_enabled: true

packages:
  - name: terraform_aws_lambda
    version: 1.4.0
    props:
      <<: [*base, *monitoring]
      function_name: api-handler

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:

lambda_props: &common_props
  runtime: inputs.runtime
  timeout: 300

packages:
  - id: api_lambda
    name: terraform_aws_lambda
    version: 1.4.0
    props:
      <<: *common_props
      function_name: api-handler

  - id: worker_lambda
    name: terraform_aws_lambda
    version: 1.4.0
    props:
      <<: *common_props
      function_name: worker-handler

Input configuration

Input types

Define blueprint inputs with types, defaults, and constraints. Supported types: string, number, bool, list, map, any.

inputs:
  environment:
    type: string
    default: dev
    description: Deployment environment
    allowed_values:
      - dev
      - staging
      - prod

  instance_count:
    type: number
    default: 2
    description: Number of instances

  enable_monitoring:
    type: bool
    default: true
    description: Enable CloudWatch monitoring

  region:
    type: string
    description: AWS region (required, no default)

Inputs without a default are required at deployment time. Inputs with a default are optional.

Allowed values

Restrict input values to specific options:

inputs:
  instance_type:
    type: string
    default: t3.micro
    allowed_values:
      - t3.micro
      - t3.small
      - t3.medium
      - t3.large

Multi-document YAML

Publish multiple blueprints from a single file using document separators (---):

name: vpc_blueprint
version: 1.0.0
packages:
  - name: terraform_aws_vpc
    version: 3.0.0
    props:
      cidr_block: inputs.vpc_cidr

---

name: database_blueprint
version: 2.0.0
packages:
  - name: terraform_aws_rds
    version: 2.1.0
    props:
      engine: postgres
      instance_class: inputs.db_instance_class

---

name: storage_blueprint
version: 1.5.0
packages:
  - name: terraform_aws_s3
    version: 2.5.0
    props:
      bucket_name: inputs.bucket_name

Each document is published as a separate blueprint.

Publishing

Publish your blueprint using the standard command:

bricks blueprint publish

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

$ bricks blueprint publish

Publishing 3 blueprint(s) from bricks.yaml...

Blueprints to be published:
  - [1/3] vpc_blueprint@1.0.0
  - [2/3] database_blueprint@2.0.0
  - [3/3] storage_blueprint@1.5.0

[1/3] Published slim blueprint: vpc_blueprint@1.0.0
[2/3] Published slim blueprint: database_blueprint@2.0.0
[3/3] Published slim blueprint: storage_blueprint@1.5.0

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.

Error	Cause
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:

bricks blueprint search -q "vpc"
bricks blueprint search -q "s3"

Inspecting package details

Get package information before adding to your blueprint:

# Full package details as JSON
bricks blueprint describe terraform_aws_vpc

# View all props with defaults
bricks blueprint get props terraform_aws_vpc@3.0.0

# View all outputs
bricks blueprint get outs terraform_aws_vpc@3.0.0

Building your YAML

Use the information from bricks blueprint describe to construct your blueprint:

1. Search and identify packages: bricks blueprint search -q "vpc"

2. Get package details: bricks blueprint describe terraform_aws_vpc

3. Create bricks.yaml with only the props you need to override

4. Verify references: use bricks blueprint get outs to confirm output keys exist before referencing them

Iterative development

Build your blueprint incrementally:

# 1. Start with minimal blueprint and publish
bricks blueprint publish

# 2. View the generated full blueprint
bricks blueprint describe test_blueprint > bricks.json

# 3. Add more packages, publish again
bricks blueprint publish

Viewing generated blueprint

After publishing, view the full hydrated blueprint with all auto-populated props and outputs:

bricks blueprint describe my_blueprint > bricks.json

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:

1. Keep existing bricks.json files working

2. Create new blueprints with bricks.yaml

3. Migrate 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:

bricks blueprint describe my_blueprint > reference.json

This shows all props, outputs, and resolved references, so you know exactly which fields to include or override.

To convert an existing blueprint:

1. Create a new bricks.yaml file

2. Copy name, version, description, tags

3. Define inputs from props

4. List packages (only override props as needed)

5. Add outputs only if customizing

6. Test with bricks blueprint publish

my-blueprint/
├── bricks.json          # Keep for reference (ignored when bricks.yaml exists)
└── bricks.yaml          # Used by CLI (takes precedence)

bricks.yaml is converted to bricks.json server-side. View the generated result with:

bricks blueprint describe my_blueprint > blueprint.json

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