Skip to main content

Streamlined Experience Base Output Port (Skeleton Entity)

This example extends the Streamlined Experience Base Output Port which uses Legacy entities with Skeleton Entity support (Witboost 2.3+). It follows the same minimal creation wizard but introduces two key files — skeleton/parameters.yaml and a %SKELETON-annotated skeleton/catalog-info.yaml.

For the legacy (non-Skeleton) version of this example, see the Streamlined Experience Base Output Port.

All examples shown here are taken from the accompanying base_streamlined_experience_skeleton.yaml template file and its companion files, which you can use as a starting point for your own Skeleton Output Port template.

Skeleton Entities in brief​

A Skeleton Entity template adds two files to the skeleton/ directory:

FileRole
skeleton/parameters.yamlDefines derived parameters computed from creation-time inputs. Read and written by Witboost at every edit cycle.
skeleton/catalog-info.yaml (with %SKELETON)Nunjucks template rendered by Witboost each time the component is read. Uses parameters.* from parameters.yaml rather than static values.*.

Because catalog-info.yaml is re-evaluated on every read rather than written once at creation time, changes to parameters.* (via the Editor Wizard) are always reflected without a re-create.

How this example differs from the Legacy version​

AspectLegacy (non-Skeleton)This example (Skeleton)
catalog-info.yamlStatic file, rendered once at creation%SKELETON file, re-rendered by Witboost on every read
Schema editsEdit template writes a new array to values.* in catalog-info.yamlEdit template writes to parameters.editSchemaColumns in parameters.yaml; catalog-info.yaml always reflects it
Schema at creationPassed as values.schemaColumns to fetch:templateDerived in parameters.yaml as editSchemaColumns

Template sections​

Component metadata​

Identical to the Legacy variant. To learn more about these fields, check the Component Metadata example.

Data contract schema​

The creation wizard presents the same two-choice boolean (inheritSchema) as in the Legacy variant. If the user chooses to inherit, an EntityRelationsPicker + EntitySelectionPicker pair retrieves the schema from an existing storage component within the same Data Product.

The critical difference is what happens after creation. In the Legacy variant, the inherited schema is written once into catalog-info.yaml via values.schemaColumns. In this Skeleton variant, the inherited schema is stored in parameters.yaml as a derived field:

# skeleton/parameters.yaml
parameters:
  editSchemaColumns: ${{ parameters.schemaDefinition.schemaColumns if parameters.inheritSchema else [] }}

catalog-info.yaml (with %SKELETON) then always renders from this derived field:

%SKELETON
...
    dataContract:
      schema: {% if parameters.editSchemaColumns | length > 0 %}
        {% for col in parameters.editSchemaColumns %}
        - name: ${{ col.name }}
          dataType: ${{ col.dataType }}
          description: ${{ col.description if col.description else '' }}
        {% endfor %}
      {% else %}[]{% endif %}

Editor Wizard: editing the schema​

For a full explanation of the schema override pattern and why it avoids the limitations of the two Legacy approaches, see Inherited Schema Override via parameters.yaml in the Templating Solutions guide.

Repository location​

Same as the Legacy variant — see Repository Location.

skeleton/parameters.yaml — derived fields and environment parameters​

In addition to editSchemaColumns, parameters.yaml is the place to define environment-specific parameters using environmentParameters:

parameters:
  editSchemaColumns: ${{ parameters.schemaDefinition.schemaColumns if parameters.inheritSchema else [] }}

environmentParameters:
  development:
    database: ${{ parameters.databaseDevelopment }}
  production:
    database: ${{ parameters.databaseProduction }}

Values under environmentParameters are accessible within catalog-info.yaml via env.* (e.g., ${{ env.database }}). This is the recommended way to handle environment-specific configuration in Skeleton Entities rather than using separate configurations.yaml files as in Legacy templates.

Usage​

Use this folder as a base for a new Skeleton Output Port template repository:

  1. Rename base_streamlined_experience_skeleton.yaml to template.yaml and base_streamlined_experience_skeleton_edit-template.yaml to edit-template.yaml.
  2. Set useCaseTemplateId and infrastructureTemplateId in both YAML files to values matching your provisioner.
  3. Replace <YOUR-GITLAB-GROUP> in template.yaml with your GitLab group path.
  4. Modify skeleton/parameters.yaml to add any further derived or environment-specific parameters your technology requires.
  5. Update skeleton/catalog-info.yaml to add the technology-specific spec.mesh.specific block.
  6. Replace all <PLACEHOLDER> markers in skeleton/catalog-info.yaml.