Add RFC0018: Context resource

Signed-off-by: Arnau Siches <arnau.siches@digital.cabinet-office.gov.uk>

content/context-resource/index.md

@@ -0,0 +1,320 @@
+---
+rfc: 0018
+start_date: 2018-08-13
+pr: openregister/registers-rfcs#31
+status: draft
+---
+
+# Context resource
+
+## Summary
+
+This RFC proposes a context resource to surface the metadata of the register.
+
+Meanwhile there is no versioning defined for metadata treat this as single
+versioned.
+
+Dependencies:
+
+* [RFC0013: Multihash](https://github.com/openregister/registers-rfcs/pull/26)
+
+
+## Motivation
+
+Currently, the register metadata is not exposed consistently. Some is exposed
+via the register resource, some via the field register and some from the
+register register.
+
+Also, the current specification and implementation don't agree on what is the
+register resource.
+
+The main driver for this RFC is to have a computed resource for the latest
+metadata in a way that makes the register self contained (i.e. a user should
+not need to interact with any other register to get the metadata for a
+register).
+
+
+## Explanation
+
+The **context** is the metadata snapshot that apply to a given log size.
+
+### Definition
+
+```elm
+type Context =
+  { id : Name
+  , copyright : String
+  , custodian : Maybe String
+  , description : Maybe String
+  , hashingAlgorithm : HashingAlgorithm
+  , licence : Maybe String
+  , rootHash : Hash
+  , schema : Schema
+  , stats : Stats
+  , status : Status
+  , title : Maybe String
+  }
+```
+
+See each section below of the explanation for each attribute.
+
+
+#### Id
+
+* Type: Name (This is defined in the specification as `[a-z][a-z0-9-]*`, the
+  future specification will make it more clear).
+
+The register identifier. The current implications for this value make it act
+as a unique identifier for the environment is belongs to. This RFC doesn't
+pretend to change this fact.
+
+
+#### Copyright
+
+* Type: String
+
+The register copyright. E.g. `© Crown copyright`. Similar to the `copyright`
+field in the Register register but required to be informed.
+
+
+#### Custodian
+
+* Type: String
+
+The same value currently exposed in the Register resource.
+
+
+#### Description
+
+* Type: Optional String
+
+The human readable description of the register.
+
+
+#### Hashing algorithm
+
+* Type: HashingAlgorithm
+
+The hashing algorithm used throughout the register.
+
+```elm
+type HashingAlgorithm =
+  { id : Name
+  , functionType : Byte
+  , digestLength : Byte
+  }
+```
+
+This depends on RFC0013
+
+|Name|Description|
+|-|-|
+|`digest-length`|The length of the digest in bytes. E.g. `0x12`|
+|`function-type`|The identifier of the hash function. E.g. `0x20`|
+|`id`| The name of the algorithm. E.g. `sha2-256`|
+
+See also: [Multihash table function type
+identifiers](https://github.com/multiformats/multihash/blob/master/hashtable.csv).
+
+
+#### Licence
+
+* Type: String (This could get restricted if/when we find a suitable list to
+  restrict the field)
+
+#### Root hash
+
+* Type: Hash
+
+The root hash for the register. Note that signatures will be addressed in
+another RFC. This is not strictly part of the metadata, it is derived from the
+data.
+
+#### Schema
+
+* Type: Schema
+
+The set of attributes that define the data allowed in the register.
+
+```elm
+type Attribute =
+  { id : Name
+  , datatype : Datatype
+  , title : Maybe String
+  , description : Maybe Text
+  }
+
+type Schema =
+  Set Attribute
+```
+
+|Name|Description|
+|-|-|
+|Id|Attribute identifier (e.g. `start-date`)|
+|Datatype|Datatype identifier (e.g. `datetime`)|
+|Title|Human readable attribute name (e.g. `Start date`)|
+|Description|Human readable attribute description (e.g. `The date a record first became relevant to a register.`)|
+
+
+#### Stats
+
+* Type: Stats
+
+The summary of objects stored in the register. This overlaps with the Register
+resource and it is not strictly part of the metadata, it is derived from the data.
+
+
+#### Status
+
+* Type: Status
+
+The status of the register. Either active or retired. This addresses the
+problem of being able to retire an entire register (see
+[issue #17](https://github.com/openregister/registers-rfcs/issues/17)).
+
+```elm
+type Status
+  = Active { startDate : Timestamp }
+  | Retired { startDate : Timestamp
+            , endDate : Timestamp
+            , replacement : Maybe Url
+            , reason : Text
+            }
+```
+
+|Name|Description|
+|-|-|
+|Start date| Date when the register started.|
+|End date| Date when the register was retired.|
+|Replacement| A URL to a register that replaces the current one.|
+|Reason| A human readable explanation of why the register is no longer active.|
+
+
+#### Title
+
+* Type: Optional String
+
+The human readable name of the register.
+
+
+### HTTP resource
+
+***
+#### Endpoint
+
+```
+GET /context
+```
+
+#### Parameters
+
+|Name|Type|Description|
+|-|-|-|
+|`total-entries` | Optional `Integer`| The log size to compute the snapshot from. Note this only applies when the metadata can be versioned.|
+
+
+#### Response attributes
+
+|Name|Type|
+|-|-|
+|`id`| Name |
+|`copyright`| String |
+|`custodian`| Optional String |
+|`description`| Optional String |
+|`hashing-algorithm`| HashingAlgorithm |
+|`licence`| String |
+|`root-hash`| Hash |
+|`schema`| List Attribute |
+|`stats`| Stats |
+|`status`| Status |
+|`title`| Optional String |
+
+#### Hashing algorithm attributes
+
+|Name|Type|
+|-|-|
+|`digest-length`| Integer |
+|`function-type`| Integer |
+|`id`| Name |
+
+See also: [Multihash table function type
+identifiers](https://github.com/multiformats/multihash/blob/master/hashtable.csv).
+
+#### Attribute attributes
+
+|Name|Type|
+|-|-|
+|`id`| Name |
+|`datatype`| Datatype |
+|`cardinality`| Cardinality |
+|`title`| Optional String |
+|`description`| Optional String |
+
+#### Stats attributes
+
+|Name|Type|
+|-|-|
+|`total-entries`| Integer |
+|`total-items`| Integer |
+|`total-records`| Integer |
+
+#### Status attributes
+
+|Name|Type|
+|-|-|
+|`start-date`| Datetime |
+|`end-date`| Optional Datetime |
+|`replacement`| Optional Url |
+|`reason`| Optional String |
+
+***
+
+***
+**EXAMPLE:**
+
+
+```http
+GET /summary HTTP/1.1
+Accept: application/json
+```
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "id": "multihash",
+  "title": "The Multihash register",
+  "description": "List of multihash codes.",
+  "custodian": "IPFS team",
+  "hashing-algorithm": {
+    "id": "sha2-256",
+    "function-type": 18,
+    "digest-length": 32
+  },
+  "stats": {
+    "total-entries": 0,
+    "total-items": 0,
+    "total-records": 0,
+  },
+  "copyright": "Copyright (c) 2016 Protocol Labs Inc.",
+  "licence": "MIT",
+  "root-hash": "1220e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  "status": { "start-date": "2018-12" },
+  "schema": [
+    {"id": "name", "datatype": "name", "cardinality": "1"},
+    {"id": "function-type", "datatype": "integer", "cardinality": "1"},
+    {"id": "digest-length", "datatype": "integer", "cardinality": "1"}
+  ]
+}
+```
+
+***
+
+### Considerations
+
+The context resource makes the register resource obsolete. Given that users
+depend on it the register resource will be available for as long as necessary.
+
+Once the context resource is available, the register resource should use a
+warning HTTP header and a Link alternate header.