Display formats

Control inherited locale and currency presentation without changing report values

Overview

The Display formats tab under Report preferences controls the viewer's locale and default currency:

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.

The preview shows how the current combination renders. Both settings can be inherited or overridden independently.

No currency conversion

Display formats never apply exchange rates. If 1000 is shown as USD and the display currency changes to EUR, the underlying value remains 1000. Currency conversion belongs in your warehouse or query.

Default does not mean forced

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

Value	Result
Ordinary count or numeric measure	Keeps its number format; no currency symbol is added
Currency-intent value without an explicit currency	Uses the report default currency
Semantic field with an explicit currency	Keeps the semantic currency
Card or column with an explicit currency	Keeps the card or column currency
Exact target with a bound currency control	Uses the selected control currency

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.

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 and default currency, or choose the inherited option shown in each selector. Saving updates the open report without 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',
    },
  },
};

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"
    }
  }'

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"
    }
  }'

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

Supported output behavior

Built-in KPI, table, Matrix, and chart presentation paths use the resolved numeric/currency policy where the value is eligible. Formatted table CSV, PDF/print, asynchronous exports, scheduled reports, and structured Briefing values preserve the applicable presentation snapshot.

The following remain intentionally separate:

Raw query and machine-readable API results remain typed numbers.
Chart CSV remains analytical data rather than localized display strings.
Arbitrary custom visual code does not receive an automatic formatting guarantee.
Free-form SQL values require explicit authoring where Semaphor cannot reliably identify the result column's meaning.

Date and datetime preferences

Date and datetime style properties are reserved in the underlying contract, but the Report preferences UI and built-in renderers do not apply them yet. Calendar timezone and week-start behavior are available today and are documented separately.

On this page