Version: 2.5

Configuration Reference

This page is the single reference for all configuration files used in tSM packaging and deployment. It covers:

package.yaml — package definition (per package)
tsm-project.yaml — project-level workspace settings
~/.tsm/ — user-level CLI configuration and credentials

These files follow the same layered model found in many enterprise development platforms: project-level settings live in the repository and are shared via Git, while user-level settings (credentials, personal preferences) live in the home directory and are never committed.

Workspace layout

A complete workspace has this structure:

tsm-project.yaml                    # project-level settings (committed to Git)

packages/
  core-common/
    package.yaml                  # package definition
    shared/                       # content area
      Register/                   # entity-type subfolder (auto-generated)
      Script/
      Form/

  ordering-sdwan/
    package.yaml
    sdwan-product/
      EntityCatalogCategory/
      EntityCatalogSpecification/
      Characteristic/
      Form/
    sdwan-fulfillment/
      Process/
      Script/

~/.tsm/                           # user-level settings (NOT committed)
  config.json                     # CLI user preferences
  credentials.json                # stored environment credentials

Key rules:

tsm-project.yaml is committed to Git — it defines the project for all team members.
packages/*/package.yaml files are committed to Git — they define each package.
~/.tsm/ is user-local. It is never committed. Each developer has their own credentials and defaults.
Entity-type subfolders inside package areas are created automatically by tSM Studio during sync.

`package.yaml`

The package definition file. One per Configuration Package. Located at:

packages/<packageId>/package.yaml

Full example

packageId: ordering-sdwan
name: Ordering / SD-WAN
version: 1.4.0
description: SD-WAN-specific ordering configuration.
ownerTeam: SDWAN

dependencies:
  - packageId: core-common
    versionRange: ">=1.0.0 <2.0.0"
    kind: required

  - packageId: ordering-core
    versionRange: ">=1.2.0 <2.0.0"
    kind: required

areas:
  - id: sdwan-product
    path: sdwan-product
    description: SD-WAN commercial and product-model configuration.
    configTypes:
      - code: cap.ordering.sdwan.product
        includeSubtree: true

  - id: sdwan-fulfillment
    path: sdwan-fulfillment
    description: SD-WAN-specific process and orchestration configuration.
    configTypes:
      - code: cap.ordering.sdwan.fulfillment
        includeSubtree: true
    entityRules:
      - entityType: Script
        include:
          - idOrCode: SDWAN.EligibilityCheck

policy:
  managed: true
  allowDelete: false
  enforceDependencies: true

Package (top-level fields)

Field	Type	Required	Description
`packageId`	String	Yes	Stable unique identifier. Should match the directory name.
`name`	String	Yes	Human-readable name shown in Studio and CLI output.
`version`	String	Yes	Package version. Semantic versioning recommended (`1.4.0`).
`description`	String		Human-readable purpose of the package.
`ownerTeam`	String		Team responsible for this package.
`dependencies`	`List<Dependency>`		Other packages this package requires.
`areas`	`List<Area>`	Yes	Content areas inside the package.
`policy`	`Policy`		Install and upgrade behavior.

Dependency

Field	Type	Required	Description
`packageId`	String	Yes	Package ID of the required dependency.
`versionRange`	String	Yes	Allowed versions (e.g. `>=1.2.0 <2.0.0`).
`kind`	Enum	Yes	`required` — must be installed. `optional` — advisory.

Version range syntax

Version ranges follow standard semver range notation:

Range	Meaning
`>=1.0.0 <2.0.0`	Any 1.x version.
`>=1.2.0 <1.3.0`	Any 1.2.x patch.
`>=0.0.1 <1.0.0`	Any pre-1.0 version.
`>=2.0.0`	Version 2.0.0 or later (no upper bound).

Area

Field	Type	Required	Description
`id`	String	Yes	Stable area identifier. Used in CLI and API references.
`path`	String	Yes	Relative directory path inside the package (default: same as `id`).
`name`	String		Optional display name.
`description`	String		What this area contains.
`configTypes`	`List<AreaConfigType>`	Yes	ConfigTypes that define the area scope.
`entityRules`	`List<EntityRule>`		Optional per-entity-type refinements.

An area should represent a business or configuration area (e.g. sdwan-product, ticketing-flow, shared), not a technical entity type. Entity-type subfolders are created automatically by Studio during sync.

AreaConfigType

Field	Type	Required	Description
`code`	String	Yes	ConfigType code used as the selection root.
`includeSubtree`	Bool	Yes	`true` — include all descendant ConfigTypes. `false` — exact match.

Example

configTypes:
  - code: cap.ordering.sdwan.product
    includeSubtree: true

This matches cap.ordering.sdwan.product and any descendant such as cap.ordering.sdwan.product.access.

EntityRule

Optional refinements per entity type within an area. Only needed for edge cases.

Field	Type	Required	Description
`entityType`	String	Yes	Entity type this rule applies to (e.g. `Form`, `Process`).
`include`	`List<Selector>`		Items to include regardless of ConfigType matching.
`exclude`	`List<Selector>`		Items to exclude even if ConfigType matches.
`filters`	`List<Filter>`		Additional filters on top of ConfigType selection.

If no entityRules are specified, the area includes all entity types matching the ConfigType scope. Only add entity rules when you need to override the default behavior (e.g. explicit includes, excludes, or filters for a specific entity type).

Each include / exclude entry is a Selector object with one field:

Field	Type	Required	Description
`idOrCode`	String	Yes	Entity identifier. If a UUID, treated as ID; otherwise treated as business code.

Prefer codes over UUIDs.

entityRules:
  - entityType: Script
    include:
      - idOrCode: SDWAN.EligibilityCheck

Filter

Narrows selection further within one entity type.

Field	Type	Required	Description
`field`	String	Yes	Entity field to filter on (for example `name`, `status`, `register.code`).
`op`	String	Yes	Filter operator aligned with Public API semantics, e.g. `eq`, `noteq`, `gt`, `gte`, `lt`, `lte`, `contains`, `notcontains`, `startswith`, `endswith`, `in`, `notin`, `empty`, `notempty`, `btw`.
`value`	String	Yes	Operator value. For list/range operators, use comma-separated values (for example `ACTIVE,PENDING` or `100,500`).

Filters map to the same API filtering model used by /search and /page: field__operator=value.

filters:
  - field: name
    op: contains
    value: sdwan

  - field: status
    op: in
    value: ACTIVE,PENDING

Policy

Controls install and upgrade behavior.

Field	Type	Default	Description
`managed`	Bool	`true`	Installed items are tracked as managed by this package.
`allowDelete`	Bool	`false`	If `true`, items missing from the package are deleted on install/upgrade.
`enforceDependencies`	Bool	`true`	Required dependencies must be satisfied before installation.

Effective selection logic

For each area, the selection works as follows:

Start with all items whose configType matches one of the area's ConfigTypes.
When includeSubtree: true, include descendant ConfigTypes.
If entityRules are present, apply per-entity-type overrides (include, exclude, filters).
Store results into the area directory, grouped by entity type in auto-generated subfolders.

CLI project and personal configuration

Current CLI configuration is documented in the CLI handbook. Shared tsm-project.yaml contains project/product/packages/components only. Environments, contexts, accounts and named workspaces belong to the personal home config; runtime profiles belong to ignored .tsm/. Use Install and connect for an empty setup. Removed alias/target-env and shared-environment examples from older product versions do not apply to this next2.5 handbook.

Workspace layout​

package.yaml​

Full example​

Package (top-level fields)​

Dependency​

Version range syntax​

Area​

AreaConfigType​

Example​

EntityRule​

Filter​

Policy​

Effective selection logic​

CLI project and personal configuration​