Introduction

  1. Background
  2. Audience
  3. Scope
  4. Versioning
  5. Reference implementation
  6. Conformance requirements
  7. Suggested reading

This specification defines the data model and HTTP interface for accessing the data held in a System of Record, the “Register”.

Background

This section is non-normative.

Back in 2015 a team at GDS started exploring how to improve digital registers. A few blog posts from then can help provide some background for where is this specification comes from.

Audience

This section is non-normative.

This specification is intended for implementers of the Register API or tools that operate on the Register API.

This specification is probably not suited to readers who need to consume data from an existing register. More approachable tutorials and guides can provide a gentler introduction to the topic.

Scope

This section is non-normative.

The scope of this specification is to define the interfaces to interact with a Register and not how to implement them. When seen adequate a non-normative description may be provided to explain how the reference implementation has addressed a topic.

Versioning

This specification aims to evolve with changes that are backwards compatible. Once that is not possible, a new version will be introduced.

A “breaking change” is a change in how Registers are defined such that is unavoidable to change the interface expectations. There are many factors that can make a change an unavoidable breaking change, the key breaking change for this version 2 to exist is the GDPR right to be forgotten. It requires the ability to make some data points inaccessible but given that a Register is immutable and relies on blob checksums to guarantee referential integrity with entries it required to change the hashing algorithm for blobs such that it would allow for an eventual redaction on a piece of data.

Reference implementation

This section is non-normative.

This specification is tested and validated by implementing every feature defined in it in the reference implementation.

Also, you can use the conformance test suite to test your implementation.

Conformance requirements

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119.

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

Examples in this specification are introduced with the words “for example“ or are set apart from the normative text with a block leaded by a label “EXAMPLE”, like this:

This is an example of an informative example with a code block as guidance:

f : a -> b

Informative notes begin with the label “NOTE” and are set apart from the normative text like this:

This is an informative note.

Informative warnings begin with the label “WARNING” and are set apart from the normative text like this:

This is an informative warning.

Informative issue blocks begin with the label “ISSUE” and are set apart from the normative text like this:

#40 This is an issue.

Experimental features are tagged as EXPERIMENTAL like this:

This is an experimental paragraph

A feature tagged as EXPERIMENTAL means the feature is being studied and it is likely to evolve possibly with breaking changes.

Informative type and function definitions may be expressed in a syntax inspired by the family of ML languages like Haskell or Elm.

A type:

type Log =
  List Entry

A function signature that reads “A function f has two parameters a and b and returns c”:

f : a -> b -> c

These types and signatures are mainly to support the narrative of this specification and interlink the different concepts in play.

Suggested reading

This section is non-normative.

The following documents might be of interest to readers of this specification.

Certificate Transparency

Google's Certificate Transparency project fixes several structural flaws in the SSL certificate system, which is the main cryptographic system that underlies all HTTPS connections.

Verifiable Data Structures

This paper describes a number of data structures and their applications that allow adding transparency to the trust model, allowing an ecosystem to evolve from pure trust, to trust but verify. By adding transparency to services, trust can be verified by the ecosystems that depend upon them.

Revocation Transparency

Like Certificate Transparency, only for revocation. Unlike CT, RT needs a recent status for the certificate, so the general idea is that client will somehow obtain and check a recent proof from the log - for example the server could retrieve it from the log regularly and serve that along with the certificate, or clients could be sent the entire revocation list.

DAT project

People often are stuck choosing between security, speed, or ease of use. Dat provides all three by using a state of the art technical foundation and user friendly tools for fast and encrypted file sharing that you control.

© Crown copyright released under the Open Government Licence.