Skeleton Parameters

Overview

The parameters.yaml file within the repository of a Skeleton Entity is structured into different sections, each serving a specific purpose:

parameters:
  # ...
values:
  # ...
readonly:
  # ...
refs:
  # ...
environmentParameters:
  # ...

Sections

`parameters`

The parameters section defines the parameters available for use within the skeleton template. Each parameter is represented as a key-value pair, where:

The key represents the parameter name, which can be referenced in the skeleton as ${{ parameters.<key> }}.
The value can be a static value or a Nunjucks expression that references other parameters using the same ${{ parameters.<key> }} syntax. Note that Nunjucks expressions are only resolved for top-level keys — expressions placed inside nested objects or arrays are not evaluated (see Limitations).

Example

parameters:
  description: This represents all the operating cashflows generating incoming or outgoing liquidity
  lifecycle: experimental
  displayName: Cash Flow
  version:
    major: 2
    minor: 0
    patch: 0
  fullVersion: ${{ parameters.version.major }}.${{ parameters.version.minor }}.${{ parameters.version.patch }}

In the corresponding skeleton (catalog-info.yaml), these parameters can be referenced as follows:

%SKELETON
kind: System
metadata:
  name: finance.cashflow.2
  description: ${{ parameters.description }}
spec:
  type: dataproduct
  lifecycle: ${{ parameters.lifecycle }}
  mesh:
    name: ${{ parameters.displayName }}
    version: ${{ parameters.fullVersion }}

`values`

The values section functions similarly to the parameters section. Its primary purpose is to ensure backward compatibility with legacy Creation Templates (see the templates' documentation for more details). It also facilitates a smooth transition from static entities to skeleton entities. However, for new entities, this section is generally optional, as all values can be directly defined within the parameters section.

In the skeleton, values can be access with the syntax ${{ values.<key> }}.

info

Values in the values section can be either:

Static values
Nunjucks expressions that reference:
- Parameters from the parameters section (i.e., ${{ parameters.<key> }})

See Limitations for known constraints on Nunjucks expressions.

Example

parameters.yaml:

parameters:
  name: finance.cashflow.2
  displayName: Finance Cash Flow
  description: A sample description for ${{ parameters.name }} # A sample description for Finance Cash Flow
  # ...
values:
  description: ${{ parameters.description }} (${{ parameters.name }}) # A sample description for Finance Cash Flow (finance.cashflow.2)

catalog-info.yaml:

%SKELETON
kind: System
metadata:
  name: ${{ parameters.name }}$
  description: ${{ values.description }} # A sample description for Finance Cash Flow (finance.cashflow.2)
# ...

`readonly`

This section contains parameters that can be read by tools like the Editor Wizard but cannot be modified by them.

In the skeleton, these parameters can be referenced using the syntax ${{ readonly.<key> }}.

info

Values in the readonly section can be either:

Static values
Nunjucks expressions that reference:
- Parameters from the parameters section (i.e., ${{ parameters.<key> }})
- Values from the values section (i.e., ${{ values.<key> }})

See Limitations for known constraints on Nunjucks expressions.

parameters.yaml:

parameters:
  # ...
values:
  # ...
readonly:
  owner: group:witboost
  domain: domain:finance

catalog-info.yaml:

%SKELETON
kind: System
metadata:
  name: ${{ parameters.name }}$
  description: ${{ values.description }}
spec:
  mesh:
    owner: ${{ readonly.owner }}
    domain: ${{ readonly.domain }}
# ...

`refs`

The refs section defines reusable values that Witboost resolves during skeleton rendering and exposes to the skeleton as ${{ refs.<key> }}.

Each ref is defined with:

provider: the built-in provider that determines where to fetch data from
config: provider-specific settings

info

Inside the refs section, Nunjucks expressions are resolved only inside config. The provider field and the ref name itself are treated as literal values.

When rendering refs.<name>.config, Witboost makes the following sections available:

Parameters from the parameters section (i.e., ${{ parameters.<key> }})
Values from the values section (i.e., ${{ values.<key> }})
Readonly parameters from the readonly section (i.e., ${{ readonly.<key> }})

For the available Nunjucks helpers, see Nunjucks Helpers for Skeleton Entities.

Example: Loading cluster information from a repository file

Scenario: The cluster information is stored in infrastructure/cluster-info.yaml relative to the parameters.yaml location. You want Witboost to read this file during rendering and inject the cluster information into your catalog-info.yaml.

Step 1: Define the ref in parameters.yaml:

parameters:
  clusterInfoFile: infrastructure/cluster-info.yaml
values:
  defaultClusterInfo:
    name: default-cluster
readonly:
  resolvedClusterInfoFile: ${{ parameters.clusterInfoFile }}
refs:
  clusterInfo:
    provider: platform.repo-file
    config:
      filePath: ${{ readonly.resolvedClusterInfoFile }}
      format: yaml
      onNotFound:
        action: fallback
        fallbackValue: ${{ values.defaultClusterInfo | dump }}

Step 2: Reference the ref in the catalog-info.yaml:

%SKELETON
kind: System
spec:
  mesh:
    clusterInfo: ${{ refs.clusterInfo | dump }}

Step 3: During rendering, Witboost reads the input file and produces the result:

Content of infrastructure/cluster-info.yaml:

name: shared-analytics
region: eu-west-1

Resulting catalog-info.yaml:

kind: System
spec:
  mesh:
    clusterInfo:
      name: shared-analytics
      region: eu-west-1

If the file doesn't exist, the ref falls back to the defaultClusterInfo value.

Built-in providers

`platform.repo-file`

Use this provider to load a file from the current entity repository.

config supports:

filePath (required): relative path of the file to load
format (optional): yaml, json, or text; if omitted, Witboost auto-detects the format from the file extension
onNotFound (optional, default onNotFound.action: skip): behavior to apply when the file does not exist
onParseError (optional, default onParseError.action: fail): behavior to apply when the file cannot be parsed

The supported error behaviors for both onNotFound.action and onParseError.action fields are:

fail: stop rendering with an error
skip: resolve the ref to null (the key referencing this ref will be present in the rendered output with a null value)
fallback: resolve the ref to the provided fallback value under onNotFound.fallbackValue or onParseError.fallbackValue

Example with format auto-detection:

parameters.yaml:

refs:
  schema:
    provider: platform.repo-file
    config:
      filePath: contracts/schema.json

catalog-info.yaml:

%SKELETON
kind: Component
spec:
  mesh:
    dataContract:
      schema: ${{ refs.schema | dump }}

Rendered catalog-info.yaml when contracts/schema.json contains { "title": "Customer Invoice" }:

kind: Component
spec:
  mesh:
    dataContract:
      schema:
        title: Customer Invoice

Example with onNotFound fallback:

refs:
  clusterInfo:
    provider: platform.repo-file
    config:
      filePath: infrastructure/cluster-info.yaml
      format: yaml
      onNotFound:
        action: fallback
        fallbackValue:
          name: default-cluster

Using with the Witboost CLI

When building descriptors locally with the witboost builder build-descriptor command, any file referenced by a platform.repo-file ref must be explicitly included using the --include option. You can specify individual files, folders, or glob patterns:

witboost builder build-descriptor \
  --entity-path ./entity \
  --environment production \
  --include infrastructure/cluster-info.yaml \
  --include contracts

`platform.published-descriptor`

Use this provider to read data from the published descriptor of a product in the Witboost marketplace, or one of its consumables.

warning

platform.published-descriptor requires Witboost Marketplace to be present, enabled, and included in your organization's Witboost license.

info

This provider retrieves the same published descriptor that Marketplace users can download from the product (or consumable) page by opening the three-dots menu next to the name and choosing Download descriptor.

If you target a product URN, you get the descriptor of that product only. The returned descriptor is not expanded with a components array.
If you target a consumable URN, you get the descriptor of that consumable only. The returned descriptor is not expanded with child consumables.

config supports:

urn (optional): a single target entity URN
urns (optional): multiple target entity URNs
environment (optional): environment to read from; if omitted, Witboost uses the current render environment
sourceKey (optional): path of the value to extract from the published descriptor; if omitted, the whole descriptor is returned
onNotFound (optional, default onNotFound.action: skip): behavior to apply when a target descriptor is not available

The supported error behaviors for the onNotFound.actionare:

fail: stop rendering with an error
skip: resolve the ref to null (the key referencing this ref will be present in the rendered output with a null value)
fallback: resolve the ref to the provided fallback value under onNotFound.fallback

At least one of urn or urns must be present.

Example with urn, environment, and sourceKey:

parameters.yaml:

refs:
  upstreamClusterInfo:
    provider: platform.published-descriptor
    config:
      urn: urn:dmb:dp:finance:customerinvoice:1
      environment: production
      sourceKey: clusterInfo

catalog-info.yaml:

%SKELETON
kind: Component
spec:
  mesh:
    clusterInfo: ${{ refs.upstreamClusterInfo | dump }}

Rendered catalog-info.yaml when the published product descriptor contains clusterInfo.name: shared-analytics:

kind: Component
spec:
  mesh:
    clusterInfo:
      name: shared-analytics

Example with urns:

parameters.yaml:

refs:
  upstreamClusterInfo:
    provider: platform.published-descriptor
    config:
      urns:
        - urn:dmb:dp:finance:customerinvoice:1
        - urn:dmb:cmp:finance:customerinvoice:1:fullview
      sourceKey: clusterInfo

catalog-info.yaml:

%SKELETON
kind: Component
spec:
  mesh:
    upstreamClusterInfo: ${{ refs.upstreamClusterInfo | dump }}

Rendered catalog-info.yaml:

kind: Component
spec:
  mesh:
    upstreamClusterInfo:
      'urn:dmb:dp:finance:customerinvoice:1':
        name: shared-analytics
      'urn:dmb:cmp:finance:customerinvoice:1:fullview':
        name: customer-facing

Example with urns read from parameters.readsFrom:

parameters.yaml:

parameters:
  readsFrom:
    - urn:dmb:dp:finance:customerinvoice:1
    - urn:dmb:cmp:finance:customerinvoice:1:fullview
refs:
  upstreamClusterInfo:
    provider: platform.published-descriptor
    config:
      urns: ${{ parameters.readsFrom | dump }}
      sourceKey: clusterInfo

catalog-info.yaml:

%SKELETON
kind: Component
spec:
  mesh:
    upstreamClusterInfo: ${{ refs.upstreamClusterInfo | dump }}

Rendered catalog-info.yaml:

kind: Component
spec:
  mesh:
    upstreamClusterInfo:
      'urn:dmb:dp:finance:customerinvoice:1':
        name: shared-analytics
      'urn:dmb:cmp:finance:customerinvoice:1:fullview':
        name: customer-facing

Example with onNotFound fallback:

refs:
  upstreamClusterInfo:
    provider: platform.published-descriptor
    config:
      urn: urn:dmb:dp:finance:customerinvoice:1
      sourceKey: clusterInfo
      onNotFound:
        action: fallback
        fallbackValue:
          name: default-cluster

warning

Refs are not guaranteed to be available in every rendering context, especially when the rendering is happening outside of a specific environment context.

In some cases, Witboost may need to render the catalog info in a context where one or more refs cannot be resolved. When this happens, expressions referencing those refs may evaluate to null or to no value at all.

To ensure reliability, it is good practice not to write catalog-info.yaml assuming that every refs.<name> value is always available. When possible, prefer configuring the ref itself to handle missing or invalid inputs through options such as fallback or skip behaviors (see options above).

`environmentParameters`

Environment parameters customize the skeleton's behavior based on the specific environment in which it is rendered.

In the skeleton catalog info, these parameters can be referenced using the syntax ${{ environmentParameters[<env>].<key> }}.

When rendering the skeleton for a specific environment, the Nunjucks environment variable is made available. This variable is an object with at least an id property representing the current environment name (e.g., development, production).

Using this, you can dynamically reference environment-specific parameters like so: ${{ environmentParameters[environment.id].<key> }}.

tip

As a shortcut, the alias env can be used in place of environmentParameters[environment.id], making expressions shorter: ${{ env.<key> }}

info

Values in the environmentParameters.<env> sections can be either:

Static values
Nunjucks expressions that reference:
- Parameters from the parameters section (i.e., ${{ parameters.<key> }})
- Values from the values section (i.e., ${{ values.<key> }})
- Readonly parameters from the readonly section (i.e., ${{ readonly.<key> }})

See Limitations for known constraints on Nunjucks expressions.

parameters.yaml:

parameters:
  # ...
values:
  # ...
readonly:
  # ...
environmentParameters:
  development:
    clusterSize: small
  production:
    clusterSize: large

catalog-info.yaml:

%SKELETON
kind: System
metadata:
  name: ${{ parameters.name }}$
  description: ${{ values.description }}
spec:
  mesh:
    cluster:
      name: {% if environment %}${{ environment.id }}-cluster{% endif %}
      size: ${{ env.clusterSize }} # equivalent to environmentParameters[environment.id].clusterSize
# ...

catalog-info.yaml (rendered in the development environment):

%SKELETON
kind: System
# ...
spec:
  mesh:
    cluster:
      name: development-cluster
      size: small
# ...

catalog-info.yaml (rendered in the production environment):

%SKELETON
kind: System
# ...
spec:
  mesh:
    cluster:
      name: production-cluster
      size: large
# ...

catalog-info.yaml (rendered in no environment):

%SKELETON
kind: System
# ...
spec:
  mesh:
    cluster:
      name: null
      size: null
# ...

warning

The environment variable, along with the env alias, may not be available in all rendering contexts. In some cases, Witboost may need to render the catalog info outside the scope of a specific environment. When this happens, expressions referencing these variables will evaluate to null.

To ensure reliability, it's good practice to check for the presence of these variables before using them.

%SKELETON
kind: System
# ...
spec:
  mesh:
    {% if environment %}
    environmentSpecificCluster:
      name: ${{ env.clusterName }} # equivalent to environmentParameters[environment.id].clusterName
      size: ${{ env.clusterSize }} # equivalent to environmentParameters[environment.id].clusterSize
    {% endif %}
# ...

Reserved Parameters

Witboost reserves and manages specific parameters to facilitate essential operations such as creating new project releases, versioning projects, and linking with Practice Shaper.

These reserved parameters are automatically mapped to specific paths in the catalog-info.yaml file when it is rendered. Some, such as readonly.__*, are fully managed by Witboost and should not be edited manually. Others, like parameters.dependsOn on components, are editable but still automatically updated when certain operations occur.

tip

For a comprehensive reference of the various fields and paths within the YAML definition of system and component entities, please refer to the Property Graph section of the documentation.

System parameters

Reserved parameters for system entities (kind: System):

Parameter	Catalog-info field	Description
`readonly.__name__`	`metadata.name`	Unique identifier for the system, automatically updated by Witboost when creating a new version of the system.
`readonly.__version__`	`spec.mesh.version`	System version, automatically incremented by Witboost when a new release or version of the system is created.
`readonly.__instanceOf__`	`spec.instanceOf`	Reference to the parent system type in the Practice Shaper

Example

parameters.yaml:

parameters:
  # ...
readonly:
  __name__: marketing.data-product-alpha.0
  __version__: 0.1.0-SNAPSHOT-3
  __instanceOf__: systemtype:default/dataproduct

skeleton catalog-info.yaml:

%SKELETON
kind: System
metadata:
  name: A sample name
  description: A sample description
spec:
  type: dataproduct

rendered catalog-info.yaml:

kind: System
metadata:
  name: marketing.data-product-alpha.0 # overridden by the `readonly.__name__` reserved parameter
  description: A sample description
spec:
  type: dataproduct
  instanceOf: systemtype:default/dataproduct # set by the `readonly.__instanceOf__` reserved parameter
  mesh:
    version: 0.1.0-SNAPSHOT-3 # set by the `readonly.__version__` reserved parameter

Component parameters

Reserved parameters for component entities (kind: Component):

Parameter	Catalog-info path	Description
`readonly.__name__`	`metadata.name`	Unique identifier for the component, automatically updated by Witboost when creating a new version of the parent system.
`readonly.__version__`	`spec.mesh.version`	Component version, automatically incremented by Witboost when a new version of the parent system is created.
`readonly.__instanceOf__`	`spec.instanceOf`	Reference to the parent component type in the Practice Shaper
`readonly.__system__`	`spec.system`	Reference to the system instance this component belongs to
`parameters.dependsOn`	`spec.mesh.dependsOn`	List of URNs of other components (part of the same system) that this component depends on. Automatically updated by Witboost when creating a new version of the parent system.

Limitations

Nunjucks expressions are not resolved inside nested objects or arrays

Nunjucks expressions are only evaluated for top-level keys within the parameters, values, readonly, and environmentParameters sections. If a key's value is a nested object or an array, any Nunjucks expressions inside it will not be evaluated and will be treated as plain strings.

The refs.<name>.config section is the exception: its content is rendered as a whole YAML object, so expressions can also be used inside nested objects and arrays there.

Does not work — the expression is inside a nested object:

parameters:
  version:
    major: 2
    minor: 0
    full: ${{ parameters.version.major }}.${{ parameters.version.minor }} # ❌ NOT resolved — inside a nested object

Works — the expression is at the top level of the section:

parameters:
  version:
    major: 2
    minor: 0
  fullVersion: ${{ parameters.version.major }}.${{ parameters.version.minor }} # ✅ Resolved — top-level key

For complex scenarios that require derived values from nested structures or arrays, define the derived expression as a top-level key in the parameters section (as shown above), or handle the composition directly in the catalog-info.yaml skeleton using Nunjucks expressions there.

Overview​

Sections​

parameters​

values​

readonly​

refs​

Built-in providers​

platform.repo-file​

platform.published-descriptor​

environmentParameters​

Reserved Parameters​

System parameters​

Component parameters​

Limitations​

Nunjucks expressions are not resolved inside nested objects or arrays​

Overview

Sections

`parameters`

`values`

`readonly`

`refs`

Built-in providers

`platform.repo-file`

`platform.published-descriptor`

`environmentParameters`

Reserved Parameters

System parameters

Component parameters

Limitations

Nunjucks expressions are not resolved inside nested objects or arrays