Model concepts

Datasets and data dictionaries

A dataset is the top-level unit of data exposed by the API. Each dataset is described by a data dictionary, which models a business domain using entities, their fields and the relationships between them.

Each data dictionary is uniquely identified by a namespace: a short lowercase string that may also contain digits and underscores, for example ${namespace}. The namespace appears in the path of all REST API URLs for that dataset.

Entities and instances

An entity represents a business concept or domain object, such as an instrument, company or security, for example ${entity}. Entities are composed of fields, each with a defined name and data type.

An instance is a single occurrence of an entity, such as an individual instrument, company or security record.

Fields and types

Field types include:

  • Primitive types: boolean, string, long, decimal, date and datetime.
  • Structs: reusable nested types that group related fields. A struct has no identity of its own; it is always part of the instance that contains it.
  • Enumerations (enums): predefined sets of allowed string values.
  • References: relationships to other entities. Because fields can refer to other entities, the data of some datasets forms a branching, tree-like structure.

Fields may represent either a single value or a collection of values (arrays).

All fields are documented in the REST API Console and in this guide. See Data fields.

Keys

Every entity contains an identifier field named id, which uniquely identifies an instance of that entity.

For entities with a time series field (see below), the key of a record is the combination of the id and the time series field. When multiple records must be stored for the same identifier and timestamp, the time series key can be extended with one or more additional fields to ensure uniqueness.

Time series

Many entities contain a time series field, which identifies the date or timestamp associated with a record. An instance can therefore have many records over time, each describing the state of the instance at that point in time.

Latest and time series views

Based on the time series field, the API provides two common views:

  • Latest view: returns the most recent record for each identifier. This is offered by the latest service.
  • Time series view: returns the records of an entity over time, or the state of an entity at a specific point in time. This is offered by the timeseries service.

Attachments

Datasets may also include attachments: binary objects associated with entity instances, used to distribute unstructured content such as documents, reports or other files.

notificationsFor questions or assistance, please contact: data.delivery@spglobal.com