Table of contents

The components of a register

Registers are primarily composed of:

  • entries
  • items
  • records

Entries

Entries contain metadata about what and when data has changed.

Entries contain the properties entry-number, entry-timestamp, item-hash and key.

The entry number is unique and defines an entry’s position within the ordered list of changes. The entry timestamp is the time when an entry was introduced to a given register, but it is no guarantee of the order of entries in a register. The entry number is.

Each entry is connected to an item by a given item hash. Entries reference items in the item-hash property using the hash derived from the corresponding item’s content.

Each key (in the key property) is a unique UTF-8 string which identifies something in a register.

Entries also contain the property index-entry-number, which is a unique number that defines an entry’s position within the ordered list of an index.

The index-entry-number property depends on indexes, which are an experimental and unreliable feature.

Items

Items contain structured data for a given primary key in a register. Items have predefined fields which are consistent within a register.

The item always contains a field which has the same name as the register. For example, every item in the local-authority-eng register has a field called local-authority-eng. The data contained in this field will be the same as the data in the key property of the entry that introduced the item to the register.

Records

A record corresponds to the latest entry for a particular key, as indicated by the entry-number property.

How entries, items and records relate

The country register, and one of its keys, ‘CI’, provides a useful example.

Using the GET /entries/{entry-number} endpoint where {entry-number} is 90 returns the 90th entry to the country register, which contains metadata. Using the GET /items/{item-hash} endpoint on that entry’s item hash returns the corresponding item, which reveals that the official-name field for the item is ‘The Republic of Cote D’Ivoire’.

The more recent 207th entry to the country register also relates to the key ‘CI’. However, this time the item hash addresses to an item that reveals that the official-name field for the corresponding item is ‘The Republic of Côte D’Ivoire’. The need to change the accent above the ‘o’ required a new entry to the register.

Using the GET /records/{key} endpoint returns the most recent entry to the register for a given {key}, with the item data already resolved. For example, GET /records/CI returns the 207th entry and its corresponding item.

Using the GET /records/CI/entries endpoint returns all entries for the key ‘CI’, meaning both the 90th and the 207th entries.