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

specmatic.yaml

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

specmatic.json

{
  "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.

specmatic.yaml

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

specmatic.json

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

specmatic.yaml

stub: "{STUB_CONFIG:\"{\\\"generative\\\": true}\"}"

specmatic.json

{
  "stub": "{STUB_CONFIG:\"{\\\"generative\\\": true}\"}"
}

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.