Docs/Core Concepts/Type System

Type system

Ptolemy uses a type-based schema system. Instrument types and market types define the custom attributes available on each record. This allows you to model any financial instrument or venue without losing schema clarity.

Types and field definitions

Every instrument belongs to exactly one instrument type (e.g. equity, bond, etf). The type determines which custom fields are available on the instrument — this is called the Entity-Attribute-Value (EAV) model.

Each type has one or more field definitions. A field definition specifies:

Property	Description
`field_key`	Machine-readable key used in API requests (e.g. sector, isin)
`field_label`	Human-readable label shown in the dashboard
`data_type`	One of: text, number, date, boolean
`is_required`	Whether the field must be supplied when creating an instrument of this type
`has_default`	Whether a default value is applied when the field is omitted
`allow_null`	Whether an explicit null value is accepted
`display_order`	Ordering in the dashboard form and export columns

Data types

Field values are stored and returned as strings regardless of data type, to avoid precision loss on numeric values. Your application is responsible for parsing them to the appropriate native type.

Data type	Accepted input	Returned as
`text`	Any string	`string`
`number`	Numeric string, integer, or float	`string (e.g. "45.82")`
`date`	ISO 8601 date (YYYY-MM-DD)	`string (e.g. "2026-04-15")`
`boolean`	`true`, `false`, `"true"`, `"false"`	`"true" or "false"`

Always treat number field values as strings in your code — never as JavaScript number or Python float. Use a dedicated decimal library to avoid floating-point precision loss on financial data.

Field values in practice

When creating or updating an instrument, pass field values as a flat key-value object using the field_values property. Keys are field_key values; values are strings (or the appropriate native type).

Creating an instrument with field values

{
  "name": "BHP Group Ltd.",
  "identifier": "bhp.ax",
  "type_id": "equity",
  "field_values": {
    "exchange": "ASX",
    "isin": "AU000000BHP4",
    "market_cap": "58400000000",
    "is_active": "true"
  }
}

The response always includes an extra_fields_snapshot — a JSONB snapshot of all current field values for that instrument, updated automatically whenever field values change.

Extras: unstructured metadata

Each instrument (and market) also supports an extras field — a free-form JSON object for unstructured data that doesn’t belong in the typed schema. Use extras for third-party IDs, internal references, or any data you want to store but don’t need to filter on.

Use field_values for

Data with a known schema, data you need to filter or sort by, required or validated fields, and data shown in the dashboard.

Use extras for

Opaque third-party IDs (Bloomberg FIGI, CUSIP), integration metadata, temporary notes, and any schema-less data you don’t need to query.

extras in a request

{
  "extras": {
    "bloomberg_figi": "BBG000BKRN43",
    "internal_id": "EQ-00412",
    "data_vendor": "refinitiv"
  }
}

Read-only types

Type schemas (instrument types, market types, time series types) and their field definitions are read-only for robot users. Only human users with the Editor or Admin role can create or modify type schemas via the dashboard or API.

This design ensures that production robot integrations don’t accidentally alter the schema used by other systems. Schema changes require a deliberate human action.