Source: http://openregister.github.io/specification/
Timestamp: 2017-09-20 16:22:08
Document Index: 409821403

Matched Legal Cases: ['§10', '§9', '§10', '§11', '§10', '§10', '§12', '§10', '§10', '§10', '§10', '§3', '§12', '§2', '§10', '§3', '§10', '§5', '§12', '§2', '§10', '§10', '§11', '§3', '§9', '§3', '§9', '§3', '§9', '§3', '§12', '§5', '§12', '§3', '§12', '§3', '§12', '§3', '§12', '§3', '§12', '§3', '§3', '§12', '§3', '§12', '§3', '§12', '§10', '§10', '§3', '§12', '§3', '§12', '§12', '§3', '§3', '§13', '§3', '§12', '§12', '§3', '§12', '§3', '§12', '§12', '§4', '§10', '§3', '§12', '§3', '§9', '§3', '§12', '§3', '§12', '§3', '§9', '§3', '§3', '§3', '§6', '§3', '§3', '§13', '§3', '§9', '§9', '§3', '§3', '§3', '§3', '§13', '§3', '§3', '§3', '§3', '§3', '§13', '§12', '§3', '§5', '§10', '§3', '§13', '§9', '§9']

Editor’s Draft, 16 May 2017
https://github.com/openregister/specification/commits/gh-pages/index.bs
Paul Downey (Government Digital Service)
Daniel Appelquist (Government Digital Service)
via the openregister/specification repository on GitHub
This document defines the resources and representations which together provide an Application Programming Interface (API) for accessing data held in an open register.
2 Infoset
3.1 Item resource
3.2 Entry resource
3.3 Record resource
3.4 Register resource
3.5 Register proof resource
3.6 Entry proof resource
3.7 Consistency proof resource
3.8 Records proof resource
3.9 Record proof resource
4 Immutable resources
5 Collection resources
5.1 Items resource
5.2 Entries resource
5.3 Item entries resource
5.4 Record entries resource
5.5 Records resource
5.6 Faceted records resource
5.7 Proofs resource
5.8 Entry proof nodes resource
6 Archive resources
6.1 Download resource
7 Streaming resources
8 HTTP Headers
9 Datatypes
9.1 String datatype
9.2 Field-name datatype
9.3 Integer datatype
9.4 Datetime datatype
9.5 Timestamp datatype
9.6 Point datatype
9.7 Multipolygon datatype
9.8 Text datatype
9.9 CURIE datatype
9.10 Item-hash datatype
9.10.1 SHA-256 item hash
9.11 Entry-reference datatype
9.12 URL datatype
10.1 Primary key field
10.2 cardinality
10.3 domain
10.4 entry-number
10.5 index-entry-number
10.6 item-hash
10.7 last-updated
10.8 field
10.9 key
11.1 Register register
11.2 Field register
11.3 Datatype register
12.1 HTML representation
12.2 JSON representation
12.3 YAML representation
12.4 CSV representation
12.5 TSV representation
12.6 JSON-LD representation
12.7 Turtle representation
12.8 Atom representation
13 Digital Proofs
13.1 Certificate transparency
13.1.1 Entry hash
13.1.2 Signed tree head
13.1.3 Verifying the register
13.1.4 Verifying an entry
13.1.5 Verifying consistency
13.1.6 Verifying the records
13.1.7 Verifying a record
14 Minting a new entry
15 Redaction
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
17.1 Transport layer security
17.1.1 HTTP Strict Transport Security
17.1.2 Content-Security-Policy
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
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 §10.8 field value.
The contents of a data item is constrained by one of a number of different §9 Datatypes.
possible confusion: "data item" and "item" mean different things <https://github.com/openregister/specification/issues/40>
3. Entity resources
3.1. Item resource
/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
/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",
"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
/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": {
"key": "E09000019",
"local-authority": "E09000019",
"name": "Islington"
3.4. Register resource
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.
An §9.3 Integer datatype value representing the number of §3.1 Item resource entities currently stored in the register.
An §9.3 Integer datatype value representing the number of §3.2 Entry resource entities currently stored in the register.
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",
"entry-number": "12",
"item-hash": "sha-256:d9178efd8febfebaaa42968648b7bdd023369c7f",
"fields": [ "address", "end-date", "school", "start-date", "name", "website" ],
"name": "Schools in the UK",
"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
/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
/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
"entry-number": "123",
"merkle-audit-path": [ "sha-256:zWJuGh1KFSTHoI1zo0gBm9mRMeCrb8nTQdnAgT3llO8=", "sha-256:e2vgurA5X7wd9dtGXNvVRl9y2ICDIRpx3bf4ucb2wbY=" ]
3.7. Consistency proof resource
/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
"merkle-consistency-nodes": [ "sha-256:MAzvw8AsFqZ8Scuc5IPfj0dzl44jJauaNXuZLQxR3bM=", "sha-256:TX/kGqrSEgHGvxLwSMyX5al14G48HyPmKbUYK0+wSCE=" ]
3.8. Records proof resource
/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
"root-hash": "sha-256:h/gTTXO9M9KARSc35nWMY1zrkISUrQYjF2ZowZgGNQg=",
"register-proof": {
"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
/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
"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
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": {
"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
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",
"key": "402020",
"sha-256:13f6de75b9f6d970691985e72a7dfa211bad1591"
"index-entry-number": "1",
"entry-number": "1",
"entry-timestamp": "2015-08-15T08:15:30Z",
"sha-256:1a0212ba5094383bcc2a0bbe1a55e3a1f1278984"
5.3. Item entries resource
/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",
"key": "33010",
"sha-256:c8844f3961a9a90812b8992ad8dbd5495e0f4782"
"index-entry-number": "133",
"entry-number": "133",
5.4. Record entries resource
/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>
5.5. Records resource
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:
"E09000016": {
"index-entry-number": "76",
"entry-number": "76",
"key": "E09000016",
5.6. Faceted records resource
/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",
"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",
"address": "200004778207",
"end-date": "2006-02-28",
"headteacher": "Mrs S Ratcliffe",
"name": "Boothan Junior School",
"school": "121728",
"start-date": "1957-10-21",
"website": "http://www.bootham.york.sch.uk/ebor"
5.7. Proofs resource
/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
/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
/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 directory with the name of the register containing
a file named "register.json" containing the §3.4 Register resource in the §12.2 JSON representation
a file named "proof.json" containing one or more digital proofs for the register in the §12.2 JSON representation
a directory named "item" containing all of the §3.1 Item resource in one or more parts in the §12.2 JSON representation
a directory named "entry" containing all of the §3.2 Entry resource in one or more files in the §12.2 JSON representation
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 ..
§4 Immutable resources SHOULD be served with a long-lived Cache-Control max-age value [RFC7234].
the §10.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 §12.2 JSON representation of an immutable §3.1 Item resource:
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"
Cache-Control: no-transform, max-age=31536000
etag: c2f6fb7ed8332561f2252359b7d6f173a376a942
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
[UNICODE] [UTF-8]
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
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"
9.5. Timestamp datatype
YYYY - MM - DD T HH : MM : SS Z
[RFC3339] timestamp, MUST be in UTC.
The following example is a valid Timestamp value:
"2001-01-31T23:20:55Z"
9.6. Point datatype
point [GEOJSON]
9.7. Multipolygon datatype
multipolygon [GEOJSON]
9.8. Text datatype
text [MARKDOWN]
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:
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>
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.
URL [URI]
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.1. Register register
11.2. Field register
11.3. Datatype register
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
suffix: .json
media-type: application/json
specification: [JSON]
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
Suffix: .yaml
Specification: [YAML]
The following example shows a §3.3 Record resource in the §12.3 YAML representation:
entry-number: "30568"
timestamp: "2015-01-02T23:59:01Z"
item-hash: "sha-256:87963123bd04263c878b36ad7ce421b8b68a07f9",
key: "402175"
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
Specification: [tabular-data-model]
12.5. TSV representation
Suffix: .tsv
Specification: [IANA-TSV]
12.6. JSON-LD representation
12.7. Turtle representation
Suffix: .ttl
Specification: [TURTLE]
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:
POST a new item in §12.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 §10.4 entry-number, and the §3.2 Entry resource is a covered by one or more §13 Digital Proofs for 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>
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
Semantics of a field cannot be significantly changed but not changed.
16.2. Forwards compatibility
Must-ignore rule.
Defaulting empty or missing values
16.3. Points of extensibility
16.3.1. Fields
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.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:
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
defined by this specification
defined by {#core-registers}
H. Butler; et al. The GeoJSON Format. URL: https://tools.ietf.org/html/draft-ietf-geojson-00
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
Anders Rundgren. JSON Cleartext Signature. URL: https://cyberphone.github.io/doc/security/jcs.html
D. Crockford. The application/json Media Type for JavaScript Object Notation (JSON). July 2006. Informational. URL: https://tools.ietf.org/html/rfc4627
KML 2.3. URL: http://www.opengeospatial.org/standards/kml/
John MacFarlane; et al. Common Markdown. URL: http://spec.commonmark.org/0.24/
B. Laurie; A. Langley; E. Kasper. Certificate Transparency. URL: https://tools.ietf.org/html/rfc6962
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 File Format Specification. 1 September 2012. Final. URL: http://www.pkware.com/documents/casestudies/APPNOTE.TXT
Mark Birbeck; Shane McCarron. CURIE Syntax 1.0. 16 December 2010. NOTE. URL: https://www.w3.org/TR/curie
Geography Markup Language (GML) Encoding Standard. URL: http://www.opengeospatial.org/standards/gml
Manu Sporny; Gregg Kellogg; Markus Lanthaler. JSON-LD 1.0. 16 January 2014. REC. URL: https://www.w3.org/TR/json-ld/
G. Klyne; C. Newman. Date and Time on the Internet: Timestamps. July 2002. Proposed Standard. URL: https://tools.ietf.org/html/rfc3339
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
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/
Eric Prud'hommeaux; Gavin Carothers. RDF 1.1 Turtle. 25 February 2014. REC. URL: https://www.w3.org/TR/turtle/
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> ↵