Registers

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.

An infoset is an unordered collection of data items.
A data item is identified within the scope of the infoset by a §9.8 field value.
The contents of a data item is constrained by one of a number of different §8 Datatypes.

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 §9 Fields and values. The set of fields which MAY be included in an item are defined in the fields field in the §10.1 Register register entry for the register.

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

The following example shows an item in the §11.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 §9.4 entry-number, an §9.5 index-entry-number, a timestamp, an §9.6 item-hash and a §9.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 §11.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 §9.1 Primary key field. That is, it is the infoset corresponding to the §3.2 Entry resource with the highest §9.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 [RFC8288] with a relation of "version-history" [RFC5829] to the §5.3 Record entries resource for this record.

The following example shows a record in the §11.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:

§9.3 domain: The Internet domain the register is available from.
§9.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 §10.1 Register register §3.3 Record resource entity describing this register.
total-items: An §8.3 Integer datatype value representing the number of §3.1 Item resource entities currently stored in the register.
total-entries: An §8.3 Integer datatype value representing the number of §3.2 Entry resource entities currently stored in the register.
total-records: An §8.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 §11.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.6 Proofs resource indicates which proofs are available.

The following example shows a Merkle-tree-based register proof in the §11.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"
}

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 §11.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 §11.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 §11.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 §11.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 [RFC8288], 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

The following example shows a set of records in the §11.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 ordered by entry number in ascending order.

The following example shows a list of entries in the §11.2 JSON representation:

[
  {
    "index-entry-number": "1",
    "entry-number": "1",
    "entry-timestamp": "2015-08-15T08:15:30Z",
    "key": "402019",
    "item-hash": [ 
        "sha-256:1a0212ba5094383bcc2a0bbe1a55e3a1f1278984"
    ]
  },
  {
    "index-entry-number": "2",
    "entry-number": "2",
    "entry-timestamp": "2015-08-20T08:15:30Z",
    "key": "402020",
    "item-hash": [
        "sha-256:13f6de75b9f6d970691985e72a7dfa211bad1591"
    ]
  },
  {
    "index-entry-number": "3",
    "entry-number": "3",
    "entry-timestamp": "2015-08-21T00:00:00Z",
    "key": "402020",
    "item-hash": [
        "sha-256:13f6de75b9f6d970691985e72a7dfa211ba00000"
    ]
  }
]

5.3. Record entries resource

Path: /record/{field-value}/entries

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

The following example shows a list of item entries in the §11.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.4. Records resource

Path: /records

All §3.3 Record resources in a register.

The following example shows a list of records in the §11.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.5. 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 §11.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.6. 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 §11.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.7. 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 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 §12 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 directory with the name of the register containing
- a file named "register.json" containing the §3.4 Register resource in the §11.2 JSON representation
- a file named "proof.json" containing one or more digital proofs for the register in the §11.2 JSON representation
- a directory named "item" containing all of the §3.1 Item resource in one or more parts in the §11.2 JSON representation
- a directory named "entry" containing all of the §3.2 Entry resource in one or more files in the §11.2 JSON representation

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

7. HTTP Headers

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

[RFC8288]
link-relations
§4 Immutable resources SHOULD be served with a long-lived Cache-Control max-age value [RFC7234].
the §9.6 item-hash SHOULD be served as the etag header value for an §3.1 Item resource.

The following example shows the HTTP headers for the §11.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

8. Datatypes

8.1. String datatype

[UNICODE] [UTF-8]

8.2. Field-name datatype

8.3. Integer datatype

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"

8.4. Datetime datatype

Datetime values MUST be recorded as Universal Coordinated Time (UTC), and not local time such as British Summer Time (BST) or other offset from UTC.
Datetime values are all valid [ISO8601].
The may be taken as a consumer as an indication of the precision, in which case it is the responsibility of the consumer to decide how the date should be interpreted.

The following examples are all valid Datetime values:

"2001", "2001-01", "2001-01-31", "2001-01-31T23:20:55"

8.5. Timestamp datatype

[RFC3339] timestamp, MUST be in UTC.

The following example is a valid Timestamp value:

"2001-01-31T23:20:55Z"

8.6. Period datatype

Where "start" and "end" are §8.4 Datetime datatype and "duration" is a §8.6.1 Duration pattern.

Period values are all valid [ISO8601]
When a Period value contains a datetime value it MUST follow the same principles described in §8.4 Datetime datatype.

The following examples are all valid Period values:

"2007-03-01T13:00:00Z/2008-05-11T15:30:00Z"
"2007-03-01T13:00:00Z/P1Y2M10DT2H30M"
"P1Y2M10DT2H30M/2008-05-11T15:30:00Z"
"P1Y2M10DT2H30M"

8.6.1. Duration pattern

Note that durations with atoms with a value of 0 MUST be removed. E.g.

P0Y1M normalises to P1M.
PT0H1M0S normalises to PT1M.

Also note that a duration MUST NOT be empty. These are invalid patterns: P, PT.

This specification chooses not to allow any decimal points in the smallest time atom.

8.7. Point datatype

point [GEOJSON]

8.8. Multipolygon datatype

multipolygon [GEOJSON]

8.9. Text datatype

text [MARKDOWN]

8.10. CURIE datatype

Used to identify a record, possibly in another register.

curie [CURIE]

8.11. 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.

8.11.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:

JSON object values MUST be sorted into lexicographical order. The keys of a JSON object must be a valid field name, which is restricted to the alphabet of lower case letters and hyphens, which makes this ordering relatively simple to implement.
All whitespace MUST be removed.
Characters in strings must be represented as follows:
- For ASCII control characters (codepoints 0x00 - 0x1f):
  - If it has a short representation (\b, \f, \n, \r, or \t), that short representation MUST be used.
  - Other control characters (such as NULL) MUST be represented as a \u00XX escape sequence. Hexadecimal digits MUST be upper-case.
- Backslash (\) and double quote (") MUST be escaped as \\ and \" respectively.
- All other characters MUST be included literally (ie unescaped). This includes forward-slash (/).

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>

8.12. Entry-reference datatype

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

8.13. URL datatype

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

URL [URI]

9. Fields

Fields defined by this specification

9.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".

9.2. cardinality

9.3. domain

9.4. entry-number

9.5. index-entry-number

9.6. item-hash

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

9.7. last-updated

9.8. field

9.9. key

10. Registers

10.1. Register register

10.2. Field register

10.3. Datatype register

11. Representations

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

11.1. HTML representation

[HTML5]

11.2. JSON representation

suffix: .json
media-type: application/json
specification: [JSON]

All field values MUST be encoded as JSON strings. When JSON needs to be in a canonical format, use the procedure defined in §8.11.1 SHA-256 item hash

11.3. YAML representation

Suffix: .yaml
Content-Type: text/yaml;charset=UTF-8
Specification: [YAML]

The following example shows a §3.3 Record resource in the §11.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>

11.4. CSV representation

Suffix: .csv
Specification: [tabular-data-model]

11.5. TSV representation

Suffix: .tsv
Content-Type: text/tab-separated-values;charset=UTF-8
Specification: [IANA-TSV]

11.6. JSON-LD representation

[JSON-LD]

11.7. Turtle representation

Suffix: .ttl
Content-Type: text/turtle;charset=UTF-8
Specification: [TURTLE]

The following example shows an §3.1 Item resource in the §11.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" ;

11.8. Atom representation

[RFC4287]

12. Digital Proofs

12.1. Certificate transparency

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

12.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 §8.11 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.

12.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.

12.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 §12.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 §8.11 Item-hash datatype and that the contents of the item generate the correct §8.11 Item-hash datatype.

12.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 §12.1.2 Signed tree head against the computed root-hash using a public key.

12.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 §12.1.2 Signed tree head against each root-hash using a public key.

12.1.6. Verifying the records

12.1.7. Verifying a record

13. Minting a new entry

To mint a new entry in the register:

POST a new item in §11.2 JSON representation to the ..mint url.. with the proposed new entry number.
The item will first appear as a new item in the store
.. status codes and error cases
.. 202 Accepted with a Location header of the §3.2 Entry resource for the new entry
The proposer can only trust it has been secured when the entry is listed in the §5.2 Entries resource with the same §9.4 entry-number, and the §3.2 Entry resource is a covered by one or more §12 Digital Proofs for the register.

The item MUST NOT contain empty fields.

14. Redaction

An item may be removed from a register, but the entry MUST NOT be removed from the register.

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>

15. Versioning and extensibility

15.1. Backwards compitability

Semantics of a field cannot be significantly changed but not changed.

15.2. Forwards compatibility

Must-ignore rule.
Defaulting empty or missing values

15.3. Points of extensibility

15.3.1. Fields

15.3.2. Resources

15.3.3. Proofs

15.3.4. Representations

A register may provide additional, possibly domain specific representations.

A register containing fields with §8.7 Point datatype or §8.8 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.

16. Security considerations

16.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.

16.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.

16.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.