Template Values

Specmatic configuration can pull in values from environment variables or system properties at runtime, through the use of template values.

Template Syntax

Template values use the format:

{ENV_VAR_NAME:defaultValue}

Resolution order:

  1. Environment variable ENV_VAR_NAME
  2. System property ENV_VAR_NAME
  3. defaultValue

Scalar Examples 

  • version: 2
contracts:
  - consumes:
    - spec.yaml
stub:
  generative: "{STUB_GENERATIVE:true}"

  • {
  "version": 2,
  "contracts": [
    {
      "consumes": [
        "spec.yaml"
      ]
    }
  ],
  "stub": {
    "generative": "{STUB_GENERATIVE:true}"
  }
}

Set the value in a shell (zsh/bash):

export STUB_GENERATIVE=false

Structured Values (Object or Array)

If the resolved value starts with { or [, it is parsed as JSON and used as an object or array value in the config.

  • version: 2
contracts:
  - consumes:
    - spec.yaml
stub: "{STUB_CONFIG:{\"generative\": true}}"
examples: "{EXAMPLE_DIRS:[\"examples/one\",\"examples/two\"]}"

  • {
  "version": 2,
  "contracts": [
    {
      "consumes": [
        "spec.yaml"
      ]
    }
  ],
  "stub": "{STUB_CONFIG:{\"generative\": true}}",
  "examples": "{EXAMPLE_DIRS:[\"examples/one\",\"examples/two\"]}"
}

Set the value in a shell:

export STUB_CONFIG='{"generative": false}'
export EXAMPLE_DIRS='["examples/one","examples/two"]'

Using a JSON-Looking Value As String

If the resolved value is a JSON string (quoted), Specmatic treats it as a string and removes the outer quotes. This lets you keep a JSON-looking value as plain text.

Example:

Set the value in a shell:

export STUB_CONFIG='"{\"generative\": true}"'

Resulting value:

{"generative": true}

Notes

  • JSON must be valid when using object/array templates.
  • Quoted JSON strings are treated as strings, not parsed into objects or arrays.