Segments

Segments turn conditions into reusable named building blocks that can be referenced by message overrides. They are the main way to keep conditional targeting readable and reviewable.

Example#

segments/platform-web.yml

description: Target web users
conditions:
  - attribute: platform
    operator: equals
    value: web

The condition syntax above (attribute/operator/value, plus the and/or/not composition and the "*" wildcard) is documented in full on the Conditions page. This page focuses on segment-specific concerns.

Segment keys#

Segment keys come from file paths relative to the segments/ directory:

Example

segments/plan-pro.yml          -> plan-pro
segments/platform-web.yml      -> platform-web
segments/dutch-account.yml     -> dutch-account

Description#

Human-readable documentation for the segment. Shown in the Catalog and used by linting.

segments/plan-pro.yml

description: Pro plan users

Conditions#

Every segment has a conditions field. It accepts the same shapes as conditions used anywhere else in Messagevisor:

a single condition object
an array of conditions (implicit and)
a logical group using and, or, or not
the literal "*" to always match

See the Conditions page for the full reference, including:

Condition kinds (attribute, feature, experiment)
Condition shapes (single, array, logical groups, wildcard)
Attribute access and dot notation for nested object attributes
Operators reference

Why use segments#

Segments help you:

reuse targeting logic across multiple message overrides
keep conditions named and reviewable
test the conditional logic directly without involving messages
understand usage in the Catalog

If the same condition appears in more than one message override, it is usually a good candidate for a segment.

Composing segments in overrides#

Messages can reference segments in their overrides using a single segment key, multiple keys, or logical group expressions over segment keys:

Single segment:

messages/dashboard/welcome.yml

overrides:
  - key: pro-users
    segments: plan-pro
    translations:
      en: Your Pro workspace is ready

Logical composition over segments inside an override:

messages/dashboard/welcome.yml

overrides:
  - key: dutch-web
    segments:
      and:
        - dutch-account
        - platform-web
    translations:
      en: Your Dutch workspace is ready

The and/or/not shape inside segments: works the same way as inside conditions:, except the leaves are segment keys instead of attribute conditions. See Overrides for the full override authoring model.

Archived#

When set to true it removes the segment from normal lint, list, and build flows:

segments/legacy-plan.yml

archived: true
description: Pre-2020 legacy plan
conditions:
  attribute: plan
  operator: equals
  value: legacy

Archived segments are skipped at evaluation time and excluded from generated datafiles.

Promotable#

When set to false it prevents this segment from being copied during promotion:

segments/environment-staging.yml

promotable: false
description: Staging environment users
conditions:
  attribute: environment
  operator: equals
  value: staging

Creating segments#

Creating manually#

You can create a segment definition file manually in the segments/ directory.

From the CLI#

Command

$ npx messagevisor create --segments --keys=$'plan-pro\nplatform-web'

This generates skeleton files with a placeholder conditions block. You fill in the actual conditions afterwards.

Testing segments#

Segment tests validate conditional logic in isolation:

tests/segments/adult.spec.yml

segment: adult
assertions:
  - description: Matches at exactly 18
    context:
      age: 18
    expectedToMatch: true
  - description: Does not match under 18
    context:
      age: 17
    expectedToMatch: false
  - matrix:
      age: [18, 25, 40]
    description: Matches adult age ${{ age }}
    context:
      age: ${{ age }}
    expectedToMatch: true

See Testing for matrix expansion and full assertion details.

Evaluating segments from the CLI#

Command

$ npx messagevisor evaluate --segment=plan-pro --context='{"plan":"pro"}'
$ npx messagevisor evaluate --segment=adult --context='{"age":21}'

This is the fastest way to debug a condition before layering message behavior on top.

Edge cases and behavior notes#

Segments vs inline conditions#

Use a segment when the logic is reusable or deserves a name. Use inline conditions on an override when the logic is small and message-specific. The underlying condition syntax is identical either way; see Conditions.

Target context can simplify segment evaluation at build time#

When a target declares known context, the builder can determine at build time whether a segment is always true, always false, or still variable. Impossible branches are removed from the datafile. See Targets.

Archived segments referenced from overrides#

An override that references an archived segment will never match at runtime. Linting flags this so you can clean up the override or unarchive the segment.