From f076df42c1831b4364166a38c400003739ca9391 Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Thu, 23 Aug 2018 15:23:43 +0100 Subject: [PATCH 1/3] Add RFC0018: Context resource Signed-off-by: Arnau Siches --- content/context-resource/index.md | 325 ++++++++++++++++++++++++++++++ 1 file changed, 325 insertions(+) create mode 100644 content/context-resource/index.md diff --git a/content/context-resource/index.md b/content/context-resource/index.md new file mode 100644 index 0000000..e002c62 --- /dev/null +++ b/content/context-resource/index.md @@ -0,0 +1,325 @@ +--- +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 current metadata of the +register. + +Dependencies: + +* [RFC0013: Multihash](../multihash/index.md) + + +## 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 : Maybe 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 it belongs to. This RFC doesn't +pretend to change this fact. + + +#### Copyright + +* Type: Optional String + +The register copyright. E.g. `© Crown copyright`. Similar to the `copyright` +field in the Register register. Must be present for any published register. + + +#### Custodian + +* Type: Optional String + +The same value currently exposed in the Register resource. Must be present for +any published register. + + +#### 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 : UVarint + , digestLength : Int + } +``` + +This depends on RFC0013 + +|Name|Description| +|-|-| +|`digest-length`|The byte length of the digest. E.g. `0x12`| +|`function-type`|The identifier of the hash function. E.g. `0x20`, `0xb220`| +|`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: Optional String + +The licence that applies to the data. Must be present for any published register. + +This could get restricted with a suitable list of licences and validated with +an external tool such that the technology allows free text but each register +controller is able to ensure what is allowed. + + +#### 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 (Active, Retired). Defaults to Active. + +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`| Optional String | +|`custodian`| Optional String | +|`description`| Optional String | +|`hashing-algorithm`| HashingAlgorithm | +|`licence`| Optional 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 /context 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. From 62b4b6c87d45dbbc568dca765e2eb767ebe3c4b7 Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Thu, 25 Oct 2018 11:32:45 +0100 Subject: [PATCH 2/3] Change stats to statistics Signed-off-by: Arnau Siches --- content/context-resource/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/content/context-resource/index.md b/content/context-resource/index.md index e002c62..3e689f3 100644 --- a/content/context-resource/index.md +++ b/content/context-resource/index.md @@ -48,7 +48,7 @@ type Context = , licence : Maybe String , rootHash : Hash , schema : Schema - , stats : Stats + , statistics : Statistics , status : Status , title : Maybe String } @@ -161,9 +161,9 @@ type Schema = |Description|Human readable attribute description (e.g. `The date a record first became relevant to a register.`)| -#### Stats +#### Statistics -* Type: Stats +* Type: Statistics 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. @@ -230,7 +230,7 @@ GET /context |`licence`| Optional String | |`root-hash`| Hash | |`schema`| List Attribute | -|`stats`| Stats | +|`statistics`| Statistics | |`status`| Status | |`title`| Optional String | @@ -255,7 +255,7 @@ identifiers](https://github.com/multiformats/multihash/blob/master/hashtable.csv |`title`| Optional String | |`description`| Optional String | -#### Stats attributes +#### Statistics attributes |Name|Type| |-|-| @@ -297,7 +297,7 @@ Content-Type: application/json "function-type": 18, "digest-length": 32 }, - "stats": { + "statistics": { "total-entries": 0, "total-items": 0, "total-records": 0, From 0052094c880b2e1519072c7269563e674c69ed1c Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Wed, 7 Nov 2018 09:38:27 +0000 Subject: [PATCH 3/3] Approve RFC0018 Signed-off-by: Arnau Siches --- README.md | 2 +- content/context-resource/index.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index fc11857..541f5fe 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ REST API). |0015|[Schema resource](content/schema-resource/index.md)|rejected|2018-08-22|#28| |0016|[Blob resource](content/blob-resource/index.md)|approved|2018-09-28|#29| |0017|[Full item redaction](content/full-item-redacted/index.md)|approved|2018-09-25|#30| -|0018|Context resource|draft|-|#31| +|0018|[Context resource](content/context-resource/index.md)|approved|2018-11-07|#31| |0019|[Boolean datatype](content/boolean-datatype/index.md)|approved|2018-08-29|#32| |0020|[Blob normalisation](content/blob-normalisation/index.md)|approved|2018-09-07|#33| |0021|[Archive resource](content/archive-resource/index.md)|approved|2018-10-31|#35| diff --git a/content/context-resource/index.md b/content/context-resource/index.md index 3e689f3..d1795da 100644 --- a/content/context-resource/index.md +++ b/content/context-resource/index.md @@ -1,8 +1,9 @@ --- rfc: 0018 start_date: 2018-08-13 +decision_date: 2018-11-07 pr: openregister/registers-rfcs#31 -status: draft +status: approved --- # Context resource