Skip to content

Catalogue definitions

Definitions give services stable identity and reusable meaning. Create a new definition only when no visible record describes the same concept.

Reusable definitions

Definition Reuse when
Entity The organization, source, publication, or subject is the same real-world thing.
Unit of measure Code, quantity, symbol, and conversion meaning match.
Metric Measurement meaning, unit, currency, adjustment, and default aggregation match.
Dimension Key, value type, source family, and semantic meaning match.
Time-series family (series group) The subject, measurement shape, time semantics, category, metrics, dimensions, units, and query contract match. Source, publication, native resolution, access, coverage, and quality may differ.
Source binding Source mode, adapter, fixed inputs, cache policy, and limits match.
Service contract Service type, accepted inputs, alternatives, and outputs match exactly.

The autocomplete selectors in service forms search visible definitions. The API equivalent is GET /v1/catalog/masters, with optional kind and q filters.

Canonical identity

Most definitions have a canonical gidUrl and a UUIDv5 gid derived from that exact URL. The URL identifies the concept; the label and description may change. Do not mint another identity to correct spelling or improve wording.

Use a stable URL under a domain controlled by the definition owner. Do not put a version, timestamp, environment name, or mutable label in the URL unless that value is part of the concept's identity.

The API quick start returned by GET /v1/authoring supplies matching URLs, UUIDs, and request paths. When creating your own values, derive the UUID with URL namespace UUIDv5.

Units and metrics

Search units by code before creating a customer-owned copy. A metric refers to one unit and declares its default aggregation. Use Custom only with a registered custom aggregation key. An adjusted monetary metric also needs its adjustment date.

A time-series metric assignment gives the metric its response key and whether it is required. The key does not replace the metric definition; it names that metric within the service contract.

Dimensions

Dimension keys use snake case. The definition fixes the value type and source family. Mark a dimension required only if every stored or source row can supply it.

For an FDW-backed service, every assigned metric and dimension key must exist in the adapter's mapped outputs. Publication fails before a mismatched contract reaches consumers.

Series groups

Choose a subject mode:

  • fixed: every observation refers to the group's selected entity;
  • per_observation: each ingested observation supplies entityGid.

Use a family to present the same measurement once even when it has several sources, publications, resolutions, or quality grades. Every new published time series should be a concrete member of a family. Existing ungrouped series remain visible as one-member families while they are migrated.

The first published member establishes the family's common signature. Publication rejects members with different subject, metric/dimension shape, units, timestamp meaning, calendar, scenario, or query contract. It also rejects duplicate variants with the same family, source, publisher, publication, and resolution.

Managers can rank sources on a grouped data service and override that order for one family. Each rank requires a rationale. Source preference is distinct from data quality and live source health; all three are shown separately to consumers.

Service contracts

Time-series and event contracts are derived when their definitions are saved through the provisioning API. CTX synchronization also creates contracts from adapter metadata. Manual contract editing is reserved for grouped services or reviewed source cases that cannot be derived.

A contract contains:

  • named, typed inputs;
  • alternative required-input groups;
  • named outputs with type, role, and optional unit;
  • deterministic limits supplied by the binding.

Contracts are immutable. A changed contract is a new revision, not an edit to an existing contract row.

Publication checks

Before accepting a service revision, QuickLookup checks identity, references, source grain, adapter mappings, field types, required metrics and dimensions, contract outputs, access, and limits. The admin shows these findings under Ready to publish?. The API returns them in the fields member of its error response.