Mappings Support

Inject external key-value data into your templates for environment-specific configurations.

What are Mappings?

Mappings are external data files that provide structured key-value pairs for use in templates. They allow you to separate data from templates, share common values, and manage environment-specific configurations.

Mappings File Format

mappings.yamlyaml

mappings:
  teams:
    devops: devops-team
    frontend: frontend-team
    backend: backend-team

  aws_account_ids:
    development: 123456789012
    staging: 234567890123
    production: 345678901234

  service_endpoints:
    api_gateway: https://api.example.com
    database: postgres://db.example.com:5432
    redis: redis://cache.example.com:6379

Using Mappings in Templates

files:
  - config.yml:
      content: |
        database_url: {{@ mappings.service_endpoints.database @}}
        owner: {{@ mappings.teams.backend @}}

Dynamic Key Access

DATABASE_URL = "{{@ mappings.environments[environment].database_url @}}"
DEBUG = {{@ mappings.environments[environment].debug @}}

Command Line Usage

Terminalbash

# Single mappings file
structkit generate --mappings-file ./mymap.yaml my-struct.yaml .

# Multiple mappings files (merged in order)
structkit generate \
  --mappings-file ./common-mappings.yaml \
  --mappings-file ./env-specific-mappings.yaml \
  my-struct.yaml .

Later files override earlier ones for conflicting keys. Deep merging is performed for nested dictionaries.

Using in the `with` Clause

folders:
  - ./infrastructure:
      struct: terraform/aws-vpc
      with:
        vpc_id: {{@ mappings.regions.us_east_1.vpc_id @}}
        subnet_ids: {{@ mappings.regions.us_east_1.subnet_ids @}}

Error Handling

Use the default filter to provide fallbacks for missing keys:

value: {{@ mappings.team.devops | default "no_team" @}}

Best Practices

Organize by context (environments, teams, regions)
Use consistent naming conventions
Keep mappings in version control
Use separate files for different environments
Provide sensible defaults for missing mappings

Template Variables

File Handling