Government Digital Service

Open Registers

Editor’s Draft,

This version:
https://openregister.github.io/specification/
Version History:
https://github.com/openregister/specification/commits/gh-pages/index.bs
Issue Tracking:
GitHub
Editors:
(Government Digital Service)
(Government Digital Service)
Bug Reports:
via the openregister/specification repository on GitHub

© Crown copyright released under the Open Government Licence.


Abstract

This document defines the resources and representations which together provide an Application Programming Interface (API) for accessing data held in an open register.

1. Introduction

An introduction to the product, independent of HMG’s use of registers ..

2. Infoset

Note: Data items in this specification are defined in terms of an information set which can be mapped to one of a number of different representations. There is no canonical representation.

possible confusion: "data item" and "item" mean different things <https://github.com/openregister/specification/issues/40>

3. Entity resources

3.1. Item resource

Path
/item/{item-hash}

An item is an unordered collection of §10 Fields and values. The set of fields which MAY be included in an item are defined in the field in the §11.1 Register register entry for the register.

An item is identified by the globally unique §10.6 item-hash calculated from its contents. Changing the item data changes the §10.6 item-hash.

The following example shows an item in the §12.2 JSON representation:
https://food-premises.register.gov.uk/item/sha-256:bdc7f29f7d2ef36f9db1ec7b4141286288a1bd79254d59b46f3a8baa3484f858
{
  "business": "company:07228130",
  "food-premises": "788112",
  "food-premises-types": ["restaurant", "cafe"],
  "local-authority": "E09000015",
  "name": "Roy’s Rolls",
  "premises": "13456079000",
  "start-date": "2015-03-01"
}

3.2. Entry resource

Path
/entry/{entry-number}

An entry is an update to a register. The register as a whole is made up of an ordered list of entries. New entries in a register are only ever appended to the end of the list; once an entry is created, it never gets changed.

An entry is an §10.4 entry-number, an §10.5 index-entry-number, a timestamp, an §10.6 item-hash and a §10.9 key. The entry-number is unique and defines the entry’s position within the ordered list of a register. The index-entry-number is unique and defines the entry’s position within the ordered list of an index. For an entry in a register the entry-number and index-entry-number are always identical. The item-hash identifies the set of §3.1 Item resource for the entry. The key represents the primary key value for the entry.

The entry resource returns an array containing a single entry.

The following example shows an entry in the §12.2 JSON representation:
[
  {
    "index-entry-number": "72",
    "entry-number": "72",
    "entry-timestamp": "2015-08-20T08:15:30Z",
    "key": "402019",
    "item-hash": [
        "sha-256:d9178efd8febfebaaa42968648b7bdd023369c7f"
    ]
  }
]

Entry timestamp semantics are not defined. <https://github.com/openregister/specification/issues/48>

Hypermedia link from entry to item? <https://github.com/openregister/specification/issues/50>

3.3. Record resource

Path
/record/{field-value}

A record is the most up-to-date §2 Infoset for a resource identified by a §10.1 Primary key field. That is, it is the infoset corresponding to the §3.2 Entry resource with the highest §10.4 entry-number for a given primary key value.

This resource is provided as a convenience: in principle, it can be computed by a client by replaying the log of all entries and finding the latest one with the given primary key value.

This resource SHOULD provide a Link: header [RFC5988] with a relation of "version-history" [RFC5829] to the §5.4 Record entries resource for this record.

The following example shows a record in the §12.2 JSON representation:
https://local-authority.register.gov.uk/record/E09000019
{
  "E09000019": {
    "index-entry-number": "72",
    "entry-number": "72",
    "entry-timestamp": "2015-08-20T08:15:30Z",
    "key": "E09000019",
    "item": [
        {
          "local-authority": "E09000019",
          "name": "Islington"
        }
    ]
  }
}

3.4. Register resource

Path
/register

The register resource is §2 Infoset with the following fields:

§10.3 domain

The Internet domain the register is available from.

§10.7 last-updated

The date the register was last updated.

The register resource also contains the following data items:

register-record

A copy of the §11.1 Register register §3.3 Record resource entity describing this register.

total-items

An §9.3 Integer datatype value representing the number of §3.1 Item resource entities currently stored in the register.

total-entries

An §9.3 Integer datatype value representing the number of §3.2 Entry resource entities currently stored in the register.

total-records

An §9.3 Integer datatype value representing the number of §3.3 Record resource entities currently stored in the register.

The following example shows a register in the §12.2 JSON representation:
{
  "domain": ".register.gov.uk",
  "last-updated": "2016-01-21T21:09:59Z",
  "register-record": {
    "entry-number": "12",
    "entry-timestamp": "2015-08-20T08:15:30Z",
    "item-hash": "sha-256:d9178efd8febfebaaa42968648b7bdd023369c7f",
    "fields": [ "address", "end-date", "school", "start-date", "name", "website" ],
    "name": "Schools in the UK",
    "phase": "beta",
    "register": "school",
    "registry": "department-of-education",
    "start-date": "2012-01-01"
  },
  "total-entries": "109001",
  "total-items": "109009",
  "total-records": "30522"
}

3.5. Register proof resource

Path
/proof/register/{proof-identifier}

A register proof is a digitally-signed demonstration of the integrity of all of the entries in a register. Given a register proof, it is possible to verify that all of the entries and items are correct, and that the entries are in the correct order.

There may be different kinds of register proof available. The exact structure of the proof will depend on the proof algorithm in use. The algorithm is identified by a proof-identifier. The §5.7 Proofs resource indicates which proofs are available.

The following example shows a Merkle-tree-based register proof in the §12.2 JSON representation:
https://school.register.gov.uk/proof/register/merkle:sha-256
{
  "proof-identifier": "merkle:sha-256",
  "total-entries": "9803348",
  "timestamp": "2015-08-20T08:15:30Z",
  "root-hash": "sha-256:JATHxRF5gczvNPP1S1WuhD8jSx2bl-WoTt8bIE3YKvU",
  "tree-head-signature":
  "BAMARzBFAiEAkKM3aRUBKhShdCyrGLdd8lYBV52FLrwqjHa5/YuzK7ECIFTlRmNuKLqbVQv0QS8nq0pAUwgbilKOR5piBAIC8LpS"
}

CT names should be mapped to a consistent "proof" field names, or held inside an envelope. <https://github.com/openregister/specification/issues/6>

3.6. Entry proof resource

Path
/proof/entry/{entry-number}/{total-entries}/{proof-identifier}

An entry proof is the information required to prove the integrity of a single entry within a register of size total-entries, given a §3.5 Register proof resource.

The important characteristic of an entry proof is that it means the client does not need to download the entire register just to verify the integrity of a single entry.

There may be different kinds of entry proof available.

The following example shows a Merkle-tree-based entry proof in the §12.2 JSON representation:
https://school.register.gov.uk/proof/entry/123/130/merkle:sha-256
{
  "proof-identifier": "merkle:sha-256",
  "entry-number": "123",
  "merkle-audit-path": [ "sha-256:zWJuGh1KFSTHoI1zo0gBm9mRMeCrb8nTQdnAgT3llO8=", "sha-256:e2vgurA5X7wd9dtGXNvVRl9y2ICDIRpx3bf4ucb2wbY=" ]
}

3.7. Consistency proof resource

Path
/proof/consistency/{total-entries-1}/{total-entries-2}/{proof-identifier}

A consistency proof proves the append-only property of a register.

The consistency proof for a register containing total-entries-2 entries and a previous version of the same register containing total-entries-1 entries (total-entries-2 > total-entries-1) is the information required to prove that the first total-entries-1 entries are equal for both, given a §3.5 Register proof resource for each version of the register.

The important characteristic of a consistency proof between two versions of a register is that the client does not need to download the entirety of either to verify consistency between the two.

There may be different kinds of consistency proof available.

The following example shows a Merkle-tree-based consistency proof in the §12.2 JSON representation:
https://school.register.gov.uk/proof/consistency/1234/1240/merkle:sha-256
{
  "proof-identifier": "merkle:sha-256",
  "merkle-consistency-nodes": [ "sha-256:MAzvw8AsFqZ8Scuc5IPfj0dzl44jJauaNXuZLQxR3bM=", "sha-256:TX/kGqrSEgHGvxLwSMyX5al14G48HyPmKbUYK0+wSCE=" ]
}

3.8. Records proof resource

Path
/proof/records/{proof-identifier}

A records proof is a digitally-signed demonstration of the integrity of all the records in a register, given a §3.5 Register proof resource. Given a records proof, it is possible to verify that all the entries and items that make up the records in a register are correct.

There may be different kinds of records proof available.

The following example shows a Merkle-tree-based records proof in the §12.2 JSON representation:
https://local-authority.register.gov.uk/proof/records/merkle:sha-256
{
  "proof-identifier": "merkle:sha-256",
  "root-hash": "sha-256:h/gTTXO9M9KARSc35nWMY1zrkISUrQYjF2ZowZgGNQg=",
  "register-proof": {
    "total-entries": "9803348",
    "timestamp": "2015-08-20T08:15:30Z",
    "root-hash": "sha-256:JATHxRF5gczvNPP1S1WuhD8jSx2bl-WoTt8bIE3YKvU",
    "tree-head-signature": "BAMARzBFAiEAkKM3aRUBKhShdCyrGLdd8lYBV52FLrwqjHa5/YuzK7ECIFTlRmNuKLqbVQv0QS8nq0pAUwgbilKOR5piBAIC8LpS"
  },
  "tree-head-signature": "YuzK7ECIFTlRmNuKLqbVQv0QS8nq0pAUwgbilKOR5piBAIC8LpS/BAMARzBFAiEAkKM3aRUBKhShdCyrGLdd8lYBV52FLrwqjHa5"
}

Records proof resource is experimental. <https://github.com/openregister/specification/issues/46>

3.9. Record proof resource

Path
/proof/record/{total-entries}/{field-value}/{proof-identifier}

A record proof is the information required to prove that a particular entry is the most recent entry for a record in a register of size total-entries, given a §3.8 Records proof resource.

The important characteristic of a record proof is that it means that the client does not need to download the entire register just to verify that an entry is the latest for a record.

There may different kinds of record proof available.

The following example shows a Merkle-tree-based record proof in the §12.2 JSON representation. This particular proof algorithm would return an array of 256 Merkle tree nodes:
https://local-authority.register.gov.uk/record/E09000019/merkle:sha-256
{
  "proof-identifier": "merkle:sha-256",
  "merkle-record-path": ["sha-256:GRt2OZyET3cslEaq1Mme/KJ46hsmk5dV2o6utknQwtY=", "sha-256:3+8RvKuH5nhFLzQr6jFzt8jaH2Fp+rBqhbfSsPVWtcw=", "sha-256:3KN32Lo6Z3eCaisbhL4OB4O0XyLuPW37Zj23nzN/h9g=", ...]
}

Record proof resource is experimental. <https://github.com/openregister/specification/issues/46>

4. Immutable resources

An immutable resource, is one whose contents will never change. An instance of an §3.1 Item resource and an §3.2 Entry resource are both deemed to be immutable.

5. Collection resources

There is a limit to how many records or entries can be returned in a single request. To fetch more, pagination is used. Pagination is supported through an http link header [RFC5988], with a link rel="next" for the next page, and rel="previous" for the previous page. On the first page, there is no "previous" link, and on the last page there is no "next" link.

define query string parameters .. <https://github.com/openregister/specification/issues/7>

if /records and /items are sets, what does that mean for pagination? <https://github.com/openregister/specification/issues/8>

5.1. Items resource

Path
/items

IMPLEMENTATION /items isn’t yet implemented. There may not be a need for this resource as it’s available in the archive. <https://github.com/openregister/specification/issues/9>

The following example shows a set of records in the §12.2 JSON representation:
{
  "sha-256:1a0212ba5094383bcc2a0bbe1a55e3a1f1278984": {
    "local-authority": "E09000019",
    "name": "Islington"
  },
  "sha-256:d9178efd8febfebaaa42968648b7bdd023369c7f": {
    "local-authority": "E09000016",
    "name": "Havering"
  }
}

what does the items resource look like in a register with multiple hashing algorithms available? <https://github.com/openregister/specification/issues/38>

5.2. Entries resource

Path
/entries

The entries resource returns the ordered list of all §3.2 Entry resources in order.

What order should /entries be in? <https://github.com/openregister/specification/issues/41>

The following example shows a list of entries in the §12.2 JSON representation:
[
  {
    "index-entry-number": "2",
    "entry-number": "2",
    "entry-timestamp": "2015-08-20T08:15:30Z",
    "key": "402020",
    "item-hash": [
        "sha-256:13f6de75b9f6d970691985e72a7dfa211bad1591"
    ]
  },
  {
    "index-entry-number": "1",
    "entry-number": "1",
    "entry-timestamp": "2015-08-15T08:15:30Z",
    "key": "402019",
    "item-hash": [ 
        "sha-256:1a0212ba5094383bcc2a0bbe1a55e3a1f1278984"
    ]
  }
]

5.3. Item entries resource

Path
/item/{item-hash}/entries

An ordered list of §3.2 Entry resource values which cite the item.

IMPLEMENTATION The resource is /item/{item-hash}/entries is new. <https://github.com/openregister/specification/issues/11>

The following example shows a list of item entries in the §12.2 JSON representation:
[
  {
    "index-entry-number": "121",
    "entry-number": "121",
    "entry-timestamp": "2015-08-20T08:15:30Z",
    "key": "33010",
    "item-hash": [
        "sha-256:c8844f3961a9a90812b8992ad8dbd5495e0f4782"
    ]
  },
  {
    "index-entry-number": "133",
    "entry-number": "133",
    "entry-timestamp": "2015-08-15T08:15:30Z",
    "key": "33010",
    "item-hash": [
        "sha-256:c8844f3961a9a90812b8992ad8dbd5495e0f4782"
    ]
  }
]

5.4. Record entries resource

Path
/record/{field-value}/entries

All of the entries which have the given §10.1 Primary key field value, in order of §10.4 entry-number.

IMPLEMENTATION the path /{key-field-name}/{field-value}/history is replaced by {record}/entries and {item}/entries <https://github.com/openregister/specification/issues/12>

The following example shows a list of item entries in the §12.2 JSON representation:
[
  {
    "index-entry-number": "121",
    "entry-number": "121",
    "entry-timestamp": "2015-08-20T08:15:30Z",
    "key": "33010",
    "item-hash": [
        "sha-256:c8844f3961a9a90812b8992ad8dbd5495e0f4782"
    ]
  },
  {
    "index-entry-number": "133",
    "entry-number": "133",
    "entry-timestamp": "2015-08-15T08:15:30Z",
    "key": "33010",
    "item-hash": [
        "sha-256:13f6de75b9f6d970691985e72a7dfa211bad1591"
    ]
  }
]

5.5. Records resource

Path
/records

All §3.3 Record resources in a register.

IMPLEMENTATION this is a set, so have changed it from a list to a hash with the record id as the key. <https://github.com/openregister/specification/issues/13>

The following example shows a list of records in the §12.2 JSON representation:
{
  "E09000019": {
    "index-entry-number": "72",
    "entry-number": "72",
    "entry-timestamp": "2015-08-20T08:15:30Z",
    "key": "E09000019",
    "item": [
        {
          "local-authority": "E09000019",
          "name": "Islington"
        }
    ]
  },
  "E09000016": {
    "index-entry-number": "76",
    "entry-number": "76",
    "entry-timestamp": "2015-08-20T08:15:30Z",
    "key": "E09000016",
    "item": [
        {
          "local-authority": "E09000016",
          "name": "Havering"
        }
    ]
  }
}

5.6. Faceted records resource

Path
/records/{field-name}/{field-value}

All §3.3 Record resources in a register which have the same value in the given field.

The following example shows a list of record entries matching a field in the §12.2 JSON representation:
https://school.register.gov.uk/records/religious-character/Quaker.json
{
  "123278": {
    "index-entry-number": "18371",
    "entry-number": "18371",
    "entry-timestamp": "2016-01-01T00:00:00Z",
    "item": [
        {
          "address": "10011891998",
          "maximum-age": "18",
          "minimum-age": "2",
          "name": "Sibford School",
          "religious-character": "Quaker",
          "school": "123278",
          "start-date": "1945-01-01",
          "website": "http://www.sibford.oxon.sch.uk"
        }
    ]
  },
  "121728": {
    "index-entry-number": "17164",
    "entry-number": "17164",
    "entry-timestamp": "2016-01-01T00:00:00Z",
    "item": [
        {
          "address": "200004778207",
          "end-date": "2006-02-28",
          "headteacher": "Mrs S Ratcliffe",
          "name": "Boothan Junior School",
          "religious-character": "Quaker",
          "school": "121728",
          "start-date": "1957-10-21",
          "website": "http://www.bootham.york.sch.uk/ebor"
        }
    ]
  }
}

5.7. Proofs resource

Path
/proofs

All of the available proof algorithms that the register supports.

The following example shows a set of register proofs in the §12.2 JSON representation:
['merkle:sha-256']

Note: A register MAY have more than one proof, to support multiple types of proof in the future.

5.8. Entry proof nodes resource

Path
/entry/{entry-number}/proofs

A set of links to the §3.5 Register proof resources and §3.6 Entry proof resources which reference this entry.

6. Archive resources

6.1. Download resource

Path
/download-register

The contents of an open register MUST be made available as an archive. The archive file MUST be capable of being used as backup of the register, with the exception of secrets used to generate §13 Digital Proofs. The archive file SHOULD be made available in a single file, but MAY be split into multiple parts if it deemed too large.

The archive contains the following files in the following structure:

A register archive MAY contain entry and item resources in the more space efficient §12.5 TSV representation.

Do we provide downloads in tar.gz or [ZIP] (the ISO/IEC 21320-1:2015 profile is open)? <https://github.com/openregister/specification/issues/14>

What is the naming convention for the archive files themselves? <https://github.com/openregister/specification/issues/15>

How about a "record" archive containing only the latest entries for each record? <https://github.com/openregister/specification/issues/16>

7. Streaming resources

we don’t yet know how to support updating an index or a cache, beyond polling. Maybe [EVENTSOURCE]? <https://github.com/openregister/specification/issues/17>

8. HTTP Headers

Table of link and other HTTP headers used by resources ..

The following example shows the HTTP headers for the §12.2 JSON representation of an immutable §3.1 Item resource:
HTTP/1.1 200 OK
Date: Fri, 22 Jan 2016 08:00:08 GMT
Expires: Sun, 22 Jan 2017 08:00:08 GMT
Link: </school/12345/entries>; rel="version-history"
Content-Type: application/json
Content-Security-Policy: default-src 'self'
Cache-Control: no-transform, max-age=31536000
etag: c2f6fb7ed8332561f2252359b7d6f173a376a942
X-Xss-Protection "1; mode=block"
X-Frame-Options "SAMEORIGIN"
X-Content-Type-Options "nosniff"
Vary: Accept-Encoding
Content-Length: 522

should provide more Content-Security-Policy values such as "https:", "data:" "unsafe-inline" and "unsafe-eval"? <https://github.com/openregister/specification/issues/18>

should we specify HTTP Public Key Pinning (HPKP)? <https://github.com/openregister/specification/issues/19>

9. Datatypes

9.1. String datatype

9.2. Field-name datatype

9.3. Integer datatype

0 - digit 1 to 9 digit 0 to 9

All values are decimal. Leading zeros are not allowed, except for the integer 0, which is represented as the string “0”. Negative values are marked with a leading “-” character ([UNICODE] 0x2D HYPHEN-MINUS).

The following examples are all valid integer values:
"100", "0", "-200"

9.4. Datetime datatype

YYYY - MM - DD T HH : MM : SS
The following examples are all valid Datetime values:
"2001", "2001-01", "2001-01-31", "2001-01-31T23:20:55"

9.5. Timestamp datatype

YYYY - MM - DD T HH : MM : SS Z
The following example is a valid Timestamp value:
"2001-01-31T23:20:55Z"

9.6. Point datatype

9.7. Multipolygon datatype

9.8. Text datatype

9.9. CURIE datatype

Used to identify a record, possibly in another register.

9.10. Item-hash datatype

A hash of the item’s contents may be used to identify the contents of an item, irrespective of where it is stored or presented.

An item-hash is a hashing algorithm and a hash value, separated by a colon (:) character. Currently there is only one valid hashing algorithm, sha-256. In future, other alternative hashing algorithms may be added to this specification. They will be distinguished by having a different string prefix.

9.10.1. SHA-256 item hash

The SHA-256 item hash of the item with a field field1 with a value of "a" and a field field2 with a value of "b" is:

sha-256:129332749e67eb9ab7390d7da2e88173367d001ac3e9e39f06e41690cd05e3ae

The sha-256 item hash is computed by serialising the item to a canonical form of JSON, and computing the SHA-256 hash, defined in [FIPS-180-4], of the resulting serial form.

The canonicalisation algorithm is as follows:

This canonicalisation algorithm is very similar to that used in [JCS], except that we stipulate an ordering of keys, and we enforce upper-case rather than lower-case hex digits.

which hashing algorithms are allowed? where do we list them? how do we allow extensibility of hashing algorithm? <https://github.com/openregister/specification/issues/39>

9.11. Entry-reference datatype

Legal documents may need to cite an individual entry, rather than the latest entry of the record.

we don’t know how to globally reference an entry, by its entry-number "register[33]", the tuple of entry-number, item-hash tuple or its fingerprint from the digital proof. <https://github.com/openregister/specification/issues/21>

9.12. URL datatype

Used to link to an external website, or other resource not held in a register.

10. Fields

We use semicolons to separate fields in a TSV/CSV value. Is this the best delimiter to use? <https://github.com/openregister/specification/issues/22>

Fields defined by this specification

10.1. Primary key field

For each register, there is a field called the primary key field. This field has the same name as the register itself: for example, in the "school" register the primary key field is also called "school".

10.2. cardinality

10.3. domain

10.4. entry-number

10.5. index-entry-number

10.6. item-hash

The item-hash field contains the §9.10 Item-hash datatype of an item.

10.7. last-updated

10.8. field

10.9. key

11. Registers

11.1. Register register

11.2. Field register

11.3. Datatype register

12. Representations

Note: JSON and other representations can have a field which is missing. These have the same semantics as an empty field.

IMPLEMENTATION currently presentation is emitting names without double-quotes, which according to jsonlint.com is not valid JSON. <https://github.com/openregister/specification/issues/26>

12.1. HTML representation

do we specify RDFa or Schema.org markup? <https://github.com/openregister/specification/issues/27>

12.2. JSON representation

All field values MUST be encoded as JSON strings.

the JSON should be in a c14n format, but no spec exists, so we will need to define what that means? <https://github.com/openregister/specification/issues/28>

12.3. YAML representation

The following example shows a §3.3 Record resource in the §12.3 YAML representation:
entry:
  entry-number: "30568"
  timestamp: "2015-01-02T23:59:01Z"
  item-hash: "sha-256:87963123bd04263c878b36ad7ce421b8b68a07f9",
  key: "402175"
item:
  address: "100101030506"
  name: "Glanaman Home Tution Centre"
  school: "402175"
  start-date: "2007-11-07"

Which data types should we use from YAML? <https://github.com/openregister/specification/issues/51>

12.4. CSV representation

12.5. TSV representation

12.6. JSON-LD representation

12.7. Turtle representation

The following example shows an §3.1 Item resource in the §12.7 Turtle representation:
@prefix field: <https://field.register.gov.uk/field/>.

<https://school.register.gov.uk/item/sha-256:af3056bd04263c878b36ad7ce421b8b68a0799>
 field:address <https://address.register.gov.uk/address/100101030506> ;
 field:name "Glanaman Home Tution Centre" ;
 field:school <https://school.register.gov.uk/record/402175> ;
 field:start-date "2007-11-07" ;

12.8. Atom representation

13. Digital Proofs

13.1. Certificate transparency

Certificate Transparency [RFC6962] is one of a number of possible methods of proving the integrity of a register.

13.1.1. Entry hash

The entry hash is the application of a supported hashing algorithm on the data contained in the §3.2 Entry resource. The §9.10 Item-hash datatype of the entry, rather than the item itself (§3.1 Item resource), is part of the raw data hashed to create the entry hash.

The entry hash is required for many operations in Certificate Transparency.

13.1.2. Signed tree head

The signed tree head for a register is the tree-head-signature property of the §3.5 Register proof resource, where the proof-identifier is specified as merkle:sha-256.

The signed tree head for a register is the signed Merkle tree root hash ([RFC6962] section 2.1) of a Merkle tree containing all entries in the register. The corresponding root-hash is also a property of the §3.5 Register proof resource.

What happens when a key is rotated? <https://github.com/openregister/specification/issues/29>

13.1.3. Verifying the register

To verify a register obtained from the §6.1 Download resource, a client must compute the Merkle tree root hash from the complete list of raw §3.2 Entry resource, as per [RFC6962] section 2.1, ensuring that it equals the root-hash of the §3.5 Register proof resource and that the same §13.1.2 Signed tree head can be generated by signing the root-hash against a public key.

The client must also verify that for each §3.2 Entry resource in the register there exists an item with the corresponding §9.10 Item-hash datatype and that the contents of the item generate the correct §9.10 Item-hash datatype.

13.1.4. Verifying an entry

The merkle-audit-path for the entry from the §3.6 Entry proof resource provides the shortest list of additional nodes in the Merkle tree required to compute the Merkle tree root hash.

To verify an entry exists in a register, given that total-entries of the §3.6 Entry proof resource equals the total-entries of the §3.5 Register proof resource, a client must combine the hash of the entry with each Merkle tree node in the merkle-audit-path consecutively, as per [RFC6962] section 2.1.1, and verify that the resulting Merkle tree root hash is equal to the root-hash of the §3.5 Register proof resource. The client should also verify the §13.1.2 Signed tree head against the computed root-hash using a public key.

13.1.5. Verifying consistency

The merkle-consistency-nodes from the §3.7 Consistency proof resource for two versions of a register provides the list of nodes in the Merkle tree required to verify that the first n entries (where n is the number of entries in the smaller register) are equal in both registers.

To verify the consistency of two versions of a register, given that total-entries-1 and total-entries-2 of the §3.7 Consistency proof resource equal the total-entries of each §3.5 Register proof resource, the client must prove that the root-hash of the §3.5 Register proof resource for the larger register can be computed using the set of consistency-proof-nodes and that the root-hash of the §3.5 Register proof resource for the smaller register can be computed using a subset of the same consistency-proof-nodes, as per [RFC6962] section 2.1.2. The client must also verify the corresponding §13.1.2 Signed tree head against each root-hash using a public key.

13.1.6. Verifying the records

13.1.7. Verifying a record

14. Minting a new entry

To mint a new entry in the register:

The item MUST NOT contain empty fields.

does a register have a standard URL to POST a new entry? <https://github.com/openregister/specification/issues/30>

15. Redaction

there is a need redaction, even for open records such as insolvency and bankruptcy. <https://github.com/openregister/specification/issues/31>

need a mechanism to flag an item as redacted. <https://github.com/openregister/specification/issues/32>

need a mechanism to mark a proof as deprecated. <https://github.com/openregister/specification/issues/33>

need a mechanism to terminate a proof and start a new proof. <https://github.com/openregister/specification/issues/34>

16. Versioning and extensibility

16.1. Backwards compitability

16.2. Forwards compatibility

16.3. Points of extensibility

16.3.1. Fields

16.3.2. Resources

16.3.3. Proofs

16.3.4. Representations

A register may provide additional, possibly domain specific representations.

A register containing fields with §9.6 Point datatype or §9.7 Multipolygon datatype values may also serve a list of items as [GML], [KML] or other geographical representation.

Additional representations for resources SHOULD be linked to from the HTML representation of the resource.

17. Security considerations

17.1. Transport layer security

A register MUST only be available over HTTPS. A register MUST NOT make content available over insecure HTTP, though a register SHOULD offer a redirect from HTTP to HTTPS.

A register contains authoritative data about a particular domain. An attacker in the middle should not be able to compromise the integrity of the data in transit. HTTPS is a basic control to prevent intermediaries from being able to alter the data in transit. For people viewing a register via a web browser, HTTPS also prevents attackers from injecting malicious content such as javascript.

17.1.1. HTTP Strict Transport Security

A register SHOULD enable HTTP Strict Transport Security [RFC6797].

The register.gov.uk domain sets a Strict-Transport-Security policy for all subdomains. This means that browsers which are aware of this policy will never attempt to use insecure HTTP to any *.register.gov.uk domain.

17.1.2. Content-Security-Policy

A register SHOULD provide a Content-Security-Policy header [CSP2]. A basic Content-Security-Policy suitable for a register is:

Content-Security-Policy: default-src 'self'

Note: if a register html view uses web assets (eg css or javascript) from another domain, the header will need to be modified to whitelist these assets.

17.2. Mint access control

17.3. Compromised proof

17.4. Stale record

17.5. Denial of service

17.6. DNS

17.7. Protecting the private key

17.8. Compromised private key

17.9. Hash clash

18. Namespaces

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

References

Normative References

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

Informative References

[CSP2]
Mike West; Adam Barth; Daniel Veditz. Content Security Policy Level 2. 21 July 2015. CR. URL: https://www.w3.org/TR/CSP2/
[FIPS-180-4]
FIPS PUB 180-4 Secure Hash Standard. URL: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf
[GEOJSON]
H. Butler; et al. The GeoJSON Format. URL: https://tools.ietf.org/html/draft-ietf-geojson-00
[IANA-TSV]
Paul Lindner. Definition of tab-separated-values (tsv). June 1993. IANA Media Type Registration. URL: http://www.iana.org/assignments/media-types/text/tab-separated-values
[ISO8601]
Representation of dates and times. International Organization for Standardization. 2004. ISO 8601:2004. URL: http://www.iso.org/iso/catalogue_detail?csnumber=40874
[JCS]
Anders Rundgren. JSON Cleartext Signature. URL: https://cyberphone.github.io/doc/security/jcs.html
[JSON]
D. Crockford. The application/json Media Type for JavaScript Object Notation (JSON). July 2006. Informational. URL: https://tools.ietf.org/html/rfc4627
[KML]
KML 2.3. URL: http://www.opengeospatial.org/standards/kml/
[MARKDOWN]
John MacFarlane; et al. Common Markdown. URL: http://spec.commonmark.org/0.24/
[RFC6962]
B. Laurie; A. Langley; E. Kasper. Certificate Transparency. URL: https://tools.ietf.org/html/rfc6962
[UNICODE]
The Unicode Standard. URL: http://www.unicode.org/versions/latest/
[URI]
T. Berners-Lee; R. Fielding; L. Masinter. Uniform Resource Identifier (URI): Generic Syntax. January 2005. Internet Standard. URL: https://tools.ietf.org/html/rfc3986
[UTF-8]
F. Yergeau. UTF-8, a transformation format of ISO 10646. November 2003. Internet Standard. URL: https://tools.ietf.org/html/rfc3629
[YAML]
Oren Ben-Kiki; Clark Evans; Ingy döt Net. YAML Ain’t Markup Language (YAML™) Version 1.2. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
[ZIP]
.ZIP File Format Specification. 1 September 2012. Final. URL: http://www.pkware.com/documents/casestudies/APPNOTE.TXT
[CURIE]
Mark Birbeck; Shane McCarron. CURIE Syntax 1.0. 16 December 2010. NOTE. URL: https://www.w3.org/TR/curie
[EVENTSOURCE]
Ian Hickson. Server-Sent Events. 3 February 2015. REC. URL: https://www.w3.org/TR/eventsource/
[GML]
Geography Markup Language (GML) Encoding Standard. URL: http://www.opengeospatial.org/standards/gml
[HTML5]
Ian Hickson; et al. HTML5. 28 October 2014. REC. URL: https://www.w3.org/TR/html5/
[JSON-LD]
Manu Sporny; Gregg Kellogg; Markus Lanthaler. JSON-LD 1.0. 16 January 2014. REC. URL: https://www.w3.org/TR/json-ld/
[RFC3339]
G. Klyne; C. Newman. Date and Time on the Internet: Timestamps. July 2002. Proposed Standard. URL: https://tools.ietf.org/html/rfc3339
[RFC4287]
M. Nottingham, Ed.; R. Sayre, Ed.. The Atom Syndication Format. December 2005. Proposed Standard. URL: https://tools.ietf.org/html/rfc4287
[RFC5829]
A. Brown; G. Clemm; J. Reschke, Ed.. Link Relation Types for Simple Version Navigation between Web Resources. April 2010. Informational. URL: https://tools.ietf.org/html/rfc5829
[RFC5988]
M. Nottingham. Web Linking. October 2010. Proposed Standard. URL: https://tools.ietf.org/html/rfc5988
[RFC6797]
J. Hodges; C. Jackson; A. Barth. HTTP Strict Transport Security (HSTS). November 2012. Proposed Standard. URL: https://tools.ietf.org/html/rfc6797
[RFC7234]
R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Caching. June 2014. Proposed Standard. URL: https://tools.ietf.org/html/rfc7234
[TABULAR-DATA-MODEL]
Jeni Tennison; Gregg Kellogg. Model for Tabular Data and Metadata on the Web. 17 December 2015. REC. URL: https://www.w3.org/TR/tabular-data-model/
[TURTLE]
Eric Prud'hommeaux; Gavin Carothers. RDF 1.1 Turtle. 25 February 2014. REC. URL: https://www.w3.org/TR/turtle/

Issues Index

possible confusion: "data item" and "item" mean different things <https://github.com/openregister/specification/issues/40>
Entry timestamp semantics are not defined. <https://github.com/openregister/specification/issues/48>
Hypermedia link from entry to item? <https://github.com/openregister/specification/issues/50>
CT names should be mapped to a consistent "proof" field names, or held inside an envelope. <https://github.com/openregister/specification/issues/6>
Records proof resource is experimental. <https://github.com/openregister/specification/issues/46>
Record proof resource is experimental. <https://github.com/openregister/specification/issues/46>
define query string parameters .. <https://github.com/openregister/specification/issues/7>
if /records and /items are sets, what does that mean for pagination? <https://github.com/openregister/specification/issues/8>
IMPLEMENTATION /items isn’t yet implemented. There may not be a need for this resource as it’s available in the archive. <https://github.com/openregister/specification/issues/9>
what does the items resource look like in a register with multiple hashing algorithms available? <https://github.com/openregister/specification/issues/38>
What order should /entries be in? <https://github.com/openregister/specification/issues/41>
IMPLEMENTATION The resource is /item/{item-hash}/entries is new. <https://github.com/openregister/specification/issues/11>
IMPLEMENTATION the path /{key-field-name}/{field-value}/history is replaced by {record}/entries and {item}/entries <https://github.com/openregister/specification/issues/12>
IMPLEMENTATION this is a set, so have changed it from a list to a hash with the record id as the key. <https://github.com/openregister/specification/issues/13>
Do we provide downloads in tar.gz or [ZIP] (the ISO/IEC 21320-1:2015 profile is open)? <https://github.com/openregister/specification/issues/14>
What is the naming convention for the archive files themselves? <https://github.com/openregister/specification/issues/15>
How about a "record" archive containing only the latest entries for each record? <https://github.com/openregister/specification/issues/16>
we don’t yet know how to support updating an index or a cache, beyond polling. Maybe [EVENTSOURCE]? <https://github.com/openregister/specification/issues/17>
should provide more Content-Security-Policy values such as "https:", "data:" "unsafe-inline" and "unsafe-eval"? <https://github.com/openregister/specification/issues/18>
should we specify HTTP Public Key Pinning (HPKP)? <https://github.com/openregister/specification/issues/19>
which hashing algorithms are allowed? where do we list them? how do we allow extensibility of hashing algorithm? <https://github.com/openregister/specification/issues/39>
we don’t know how to globally reference an entry, by its entry-number "register[33]", the tuple of entry-number, item-hash tuple or its fingerprint from the digital proof. <https://github.com/openregister/specification/issues/21>
We use semicolons to separate fields in a TSV/CSV value. Is this the best delimiter to use? <https://github.com/openregister/specification/issues/22>
IMPLEMENTATION currently presentation is emitting names without double-quotes, which according to jsonlint.com is not valid JSON. <https://github.com/openregister/specification/issues/26>
do we specify RDFa or Schema.org markup? <https://github.com/openregister/specification/issues/27>
the JSON should be in a c14n format, but no spec exists, so we will need to define what that means? <https://github.com/openregister/specification/issues/28>
Which data types should we use from YAML? <https://github.com/openregister/specification/issues/51>
What happens when a key is rotated? <https://github.com/openregister/specification/issues/29>
does a register have a standard URL to POST a new entry? <https://github.com/openregister/specification/issues/30>
there is a need redaction, even for open records such as insolvency and bankruptcy. <https://github.com/openregister/specification/issues/31>
need a mechanism to flag an item as redacted. <https://github.com/openregister/specification/issues/32>
need a mechanism to mark a proof as deprecated. <https://github.com/openregister/specification/issues/33>
need a mechanism to terminate a proof and start a new proof. <https://github.com/openregister/specification/issues/34>