Documentation · Data model

Entity structure

Our bulk files and API describe the world as entities: people, companies, vessels and the listings that name them. This page explains the JSON object for one entity, how entities refer to each other, and how files of entities are laid out.

Entities

An entity is one JSON object with a few fixed fields and a properties object. This is a person from the Monaco asset-freeze list as it appears in entities.ftm.json:

{
  "id": "crown-379759982",
  "caption": "SULTAN AZIZ AZAM",
  "schema": "Person",
  "properties": {
    "name": [
      "SULTAN AZIZ AZAM"
    ],
    "topics": [
      "sanction"
    ],
    "alias": [
      "AZIZ AZAM",
      "SULTAN AZIZ",
      "SULTAN AZZIZ AZZAM",
      "SULTAN AZIZ EZZAM"
    ],
    "birthDate": [
      "1985"
    ],
    "nationality": [
      "af"
    ],
    "notes": [
      "Nat: AFGHANISTAN · DOB: 1985"
    ]
  },
  "referents": [],
  "datasets": [
    "monaco_siccfin_liste_nationale_de_gel_des_fonds"
  ],
  "first_seen": "2026-09-24T11:22:17.136797+00:00",
  "last_seen": "2026-09-24T11:22:17.136797+00:00",
  "last_change": "2026-09-24T11:22:17.136797+00:00",
  "target": true,
  "canonical_id": "crown-e-d9d87cf7-081f-41c3-bcd3-42a1194a9e9d"
}

Every property value is a list, even when the publisher gives one value, because many publishers give several names or birth dates for the same person. Which properties each schema can carry is in the data dictionary.

Fixed fields

Field	Type	Description
`id`	string	Our record ID: `crown-` plus the record number in our register. Stable for as long as the publisher keeps the listing. See Identifiers and deduplication.
`schema`	string	The entity type, such as `Person` or `Vessel`. See Schema types.
`caption`	string	A display name for the entity. See How captions are chosen.
`properties`	object	Property names mapped to lists of values.
`datasets`	list of strings	The source register the record comes from, as a short name. Always one value today, because each record comes from one register.
`referents`	list of strings	Earlier IDs that now point to this entity. Always empty today: we do not yet retire or merge IDs into one another.
`target`	boolean	True for the listed party, absent on the `Sanction` entity. See Target.
`canonical_id`	string	Present when the record has been grouped with records of the same party in other registers: `crown-e-` plus a UUID. See How records are merged.
`first_seen`	timestamp	See Timestamps.
`last_seen`	timestamp	See Timestamps.
`last_change`	timestamp	See Timestamps.

How captions are chosen

The caption of a party is its primary name exactly as the publisher wrote it, including the publisher’s capitalization and word order (AZAM, SULTAN AZIZ on one list, SULTAN AZIZ AZAM on another). We do not yet pick a preferred spelling across registers. The caption of a Sanction entity is its programme, or the register name when there is no programme.

Timestamps

Timestamps are ISO 8601 in UTC with a time-zone offset.

Field	Meaning today
`first_seen`	When our collector first loaded this record from the publisher.
`last_seen`	When the record was last confirmed in the publisher’s list, at the most recent successful run of that source.
`last_change`	Set to the same value as `last_seen` for now. A true “last changed” date needs per-run snapshots, which are planned (data backlog item 18).

These dates describe our collection, not the listing. When you need the date a person was listed, use the listingDate of the Sanction entity where the publisher gives one, or check the publisher’s own record.

References between entities

A property of type entity holds the ID of another entity. Today the only such property is entity on the Sanction entity, which points to the listed party. The listing for the person above is a separate line in the same file:

{
  "id": "crown-379759982-sanction",
  "schema": "Sanction",
  "caption": "Personne physique",
  "properties": {
    "entity": [
      "crown-379759982"
    ],
    "authority": [
      "Monaco SICCFIN — Liste nationale de gel des fonds"
    ],
    "program": [
      "Personne physique"
    ]
  },
  "datasets": [
    "monaco_siccfin_liste_nationale_de_gel_des_fonds"
  ],
  "first_seen": "2026-09-24T11:22:17.136797+00:00",
  "last_seen": "2026-09-24T11:22:17.136797+00:00",
  "last_change": "2026-09-24T11:22:17.136797+00:00"
}

Here the publisher put the party type (“Personne physique”) in its programme column, and we keep its wording. Read Sanction fields as the publisher’s, not as a classification of ours.

Relationships

FollowTheMoney models links such as ownership, directorships, family ties and associates as entities of their own that point to two parties. We do not publish any relationship entities yet. Beneficial-ownership filings (for example the UK register of people with significant control) are held in our registry tables but are not part of the entity files. Building a relationship model is planned work (data backlog item 23).

Files of entities

Our entity files are JSON Lines: one complete JSON object per line, with no surrounding array, so a file of any size can be read one line at a time. In entities.ftm.json each party is followed on the next line by its Sanction entity. The files for each collection, with sizes and checksums, are listed in Using the bulk data; how to apply changes between builds is in Delta files.

# after downloading a collection's file
head -2 entities.ftm.json          # first party and its listing
wc -l entities.ftm.json            # number of entities (parties + listings)

Tools for FollowTheMoney data

Because our files follow FollowTheMoney, tools written for that model can read them. These are third-party projects; we do not maintain them.

FollowTheMoney documentation, including the reference for every schema and property type.
The followthemoney Python package, which reads, validates and converts entity files.

Last updated 2026-10-04