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:
  # ...
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.

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> }})

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> }})

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 }}
# ...

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> }})

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.