Template Values

Specmatic configuration can pull in values from environment variables or Java 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 3 (recommended)

YAML

specmatic.yaml

version: 3
dependencies:
  services:
    - service:
        $ref: "#/components/services/apiOrderV3"
  settings: "{STUB_CONFIG:{\"generative\": true}}"
components:
  sources:
    specmaticOrderContracts:
      git:
        url: https://github.com/specmatic/specmatic-order-contracts.git
  services:
    apiOrderV3:
      description: API Order V3
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/specmaticOrderContracts"
            specs:
              - io/specmatic/examples/store/openapi/api_order_v3.yaml

specmatic.json

specmatic.json

{
  "version": 3,
  "dependencies": {
    "services": [
      {
        "service": {
          "$ref": "#/components/services/apiOrderV3"
        }
      }
    ],
    "settings": "{STUB_CONFIG:{\"generative\": true}}"
  },
  "components": {
    "sources": {
      "specmaticOrderContracts": {
        "git": {
          "url": "https://github.com/specmatic/specmatic-order-contracts.git"
        }
      }
    },
    "services": {
      "apiOrderV3": {
        "description": "API Order V3",
        "definitions": [
          {
            "definition": {
              "source": {
                "$ref": "#/components/sources/specmaticOrderContracts"
              },
              "specs": [
                "io/specmatic/examples/store/openapi/api_order_v3.yaml"
              ]
            }
          }
        ]
      }
    }
  }
}

Version 2

YAML

specmatic.yaml

version: 2
contracts:
  - git:
      url: https://github.com/specmatic/specmatic-order-contracts.git
    consumes:
      - io/specmatic/examples/store/openapi/api_order_v3.yaml
stub:
  generative: "{STUB_GENERATIVE:true}"

JSON

specmatic.json

{
  "version": 2,
  "contracts": [
    {
      "git": {
        "url": "https://github.com/specmatic/specmatic-order-contracts.git"
      },
      "consumes": [
        "io/specmatic/examples/store/openapi/api_order_v3.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 3 (recommended)

YAML

specmatic.yaml

version: 3
dependencies:
  services:
    - service:
        $ref: "#/components/services/apiOrderV3"
  settings:
    generative: "{STUB_GENERATIVE:true}"
components:
  sources:
    specmaticOrderContracts:
      git:
        url: https://github.com/specmatic/specmatic-order-contracts.git
  services:
    apiOrderV3:
      description: API Order V3
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/specmaticOrderContracts"
            specs:
              - io/specmatic/examples/store/openapi/api_order_v3.yaml

specmatic.json

specmatic.json

{
  "version": 3,
  "dependencies": {
    "services": [
      {
        "service": {
          "$ref": "#/components/services/apiOrderV3"
        }
      }
    ],
    "settings": {
      "generative": "{STUB_GENERATIVE:true}"
    }
  },
  "components": {
    "sources": {
      "specmaticOrderContracts": {
        "git": {
          "url": "https://github.com/specmatic/specmatic-order-contracts.git"
        }
      }
    },
    "services": {
      "apiOrderV3": {
        "description": "API Order V3",
        "definitions": [
          {
            "definition": {
              "source": {
                "$ref": "#/components/sources/specmaticOrderContracts"
              },
              "specs": [
                "io/specmatic/examples/store/openapi/api_order_v3.yaml"
              ]
            }
          }
        ]
      }
    }
  }
}

Version 2

YAML

specmatic.yaml

version: 2
contracts:
  - git:
      url: https://github.com/specmatic/specmatic-order-contracts.git
    consumes:
      - io/specmatic/examples/store/openapi/api_order_v3.yaml
stub: "{STUB_CONFIG:{\"generative\": true}}"

JSON

specmatic.json

{
  "version": 2,
  "contracts": [
    {
      "git": {
        "url": "https://github.com/specmatic/specmatic-order-contracts.git"
      },
      "consumes": [
        "io/specmatic/examples/store/openapi/api_order_v3.yaml"
      ]
    }
  ],
  "stub": "{STUB_CONFIG:{\"generative\": true}}"
}

Set the value in a shell:

export STUB_CONFIG='{"generative": false}'

Notes

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