Display formats

Overview

The Display formats tab under Report preferences controls the viewer's locale, default currency, and automatic date and datetime styles:

• Locale controls grouping separators, decimal separators, currency-symbol placement, and other locale-aware numeric conventions.
• Default currency supplies a currency code when a value has currency intent but no more-specific authored currency.
• Date format controls automatic presentation of civil dates and grouped day, week, and month values.
• Date & time date format and Date & time time format independently control the date and time portions of automatic datetime presentation.

The previews use the current locale so you can see the complete result before saving. Every setting is inherited or overridden independently.

Default does not mean forced

The report currency is a fallback, not a global instruction to put a currency symbol on every number.

This preserves author intent while giving viewers and embedding applications a predictable fallback.

Precedence

For each applicable formatting property, Semaphor resolves:

system fallback
→ resolved report preference
→ semantic field format
→ saved card or column format
→ explicitly bound currency control

Later layers override earlier layers. The control layer applies only to the exact visual target the author bound.

For temporal values, a valid explicit card or column format wins over the viewer preference. Grouped dates then use a same-grain semantic format when one exists; otherwise the viewer's automatic date or datetime style is used.

Example: inherited locale, explicit currency

Suppose a viewer inherits:

{
  "locale": "de-DE",
  "defaultCurrency": "EUR"
}

A revenue metric explicitly authored as GBP continues to use GBP, but it uses the inherited German locale when the authored format does not specify a locale. A value of 1000 can therefore display as 1.000,00 £.

Example: currency control

An author can bind a currency control to a specific KPI metric or table/chart target. Selecting EUR changes that target's currency presentation. Other metrics and unbound cards remain unchanged, and the change does not issue a new analytical data query.

Configure display-format preferences

Personal preference

Open More options → Report preferences → Display formats. Choose a locale, default currency, date style, datetime date style, and datetime time style, or choose the inherited option shown in each selector. Saving updates presentation in the open report without refetching analytical data or generating a new token.

Initial embedded-session preference

Pass sparse display-format inputs in the token request:

const requestBody = {
  dashboardId: DASHBOARD_ID,
  dashboardSecret: DASHBOARD_SECRET,
  params: {
    valueFormatPreferences: {
      locale: 'en-NZ',
      defaultCurrency: 'NZD',
      dateStyle: 'long',
      dateTime: {
        dateStyle: 'medium',
        timeStyle: 'short',
      },
    },
  },
};

An identified viewer's personal preferences take precedence. The token value then precedes tenant, organization, and system defaults.

Organization default

Administrators can set the default inherited by organization users and tenants:

curl -X PUT https://semaphor.cloud/api/management/v1/organizations/{orgId} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "defaultValueFormatContext": {
      "locale": "de-DE",
      "defaultCurrency": "EUR",
      "dateStyle": "long",
      "dateTime": {
        "dateStyle": "medium",
        "timeStyle": "short"
      }
    }
  }'

Set defaultValueFormatContext to null to clear the organization default.

Tenant default

Administrators can set a sparse tenant default with the Management API:

curl -X PUT https://semaphor.cloud/api/management/v1/tenants/{tenantId} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "defaultValueFormatContext": {
      "locale": "en-NZ",
      "defaultCurrency": "NZD",
      "dateStyle": "short",
      "dateTime": {
        "dateStyle": "short",
        "timeStyle": "medium"
      }
    }
  }'

Set defaultValueFormatContext to null to clear the tenant default and reveal the organization fallback.

Date and datetime behavior

Semaphor keeps temporal identity separate from presentation:

• A civil date such as 2026-07-31 is formatted as a calendar date without a timezone shift.
• A wall datetime is formatted as the same local clock fields it represents.
• A true instant is converted once into the report Calendar timezone before it is displayed.
• Grouped values keep their canonical analytical bucket for sorting, filtering, drill, and interactions. Only their visible label changes.

The short, medium, and long choices are locale-aware. Product-authored structural text such as Week of, Q, and FY remains English; full product internationalization is separate from value localization.

Automatic viewer fallback applies to config-driven raw detail tables, declared date columns on SQL-only detail tables, and grouped temporal values in regular tables, Cartesian charts, custom visuals, aggregate tables, and pivot tables. Matrix temporal axes use the same viewer fallback through their canonical v2 member metadata. Explicit applicable column, card/axis, or semantic formats continue to take precedence.

Supported output behavior

Eligible built-in number/currency paths and the temporal surfaces named above use the resolved viewer policy. Dashboard-card CSV and PDF downloads, PDF/print, asynchronous formatted exports, scheduled reports, and structured Briefing values preserve the presentation captured when the artifact is created for the visual families that support those delivery modes. Matrix uses the same policy in the interactive table, browser CSV, and rendered-page PDF/Briefing paths; it does not currently add a Matrix-specific asynchronous or scheduled attachment protocol.

The following remain intentionally separate:

• Raw query and machine-readable API results retain canonical values.
• An explicitly raw SQL-editor export remains raw. A CSV or PDF downloaded for a dashboard card is a formatted artifact.
• Arbitrary custom visual code does not receive an automatic formatting guarantee.
• SQL-only detail-table dates require an explicit date column declaration. SQL plus Python-shaped output keeps its authored column-settings behavior.
• Standalone TIME, relative-time presentation, and date-valued KPI output are not changed by these preferences.

Related

• Report Preferences
• Calendar
• KPI Charts
• Token API
• Update organization report defaults