From 71eef862c948a6f537be677074223c6e9b1dc725 Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Fri, 9 Feb 2018 15:36:28 +0000 Subject: [PATCH 1/6] Add RFC for the schema resource Before this RFC we explored a few options including JSON-LD, keep something similar as the register register and field register or JSON Schema. None of them is fit for purpose, mainly because our custom datatype system. Signed-off-by: Arnau Siches --- content/schema-resource/index.md | 115 +++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 content/schema-resource/index.md diff --git a/content/schema-resource/index.md b/content/schema-resource/index.md new file mode 100644 index 0000000..71ecf5f --- /dev/null +++ b/content/schema-resource/index.md @@ -0,0 +1,115 @@ +--- +rfc: +start_date: 2018-02-09 +pr: +status: draft +--- + +# Schema resource + +## Summary + +This RFC proposes a schema resource to describe the register set of attributes +with their datatypes. + + +## Motivation + +The current mechanisms to get information about the schema are the `GET +/register` endpoint or the Register register complemented with the Field +register. It is cumbersome to get the full picture of the schema and, even +more the day the schema gets the ability to evolve. + + +## Explanation + +*** +### Endpoint + +``` +GET /schema +``` + +### Parameters + +|Name|Type|Description| +|-|-|-| +|`log-size` | Optional `Integer`| Set the log size to the given entry number instead of the latest value.| + + +### Response attributes + +|Name|Type|Description| +|-|-|-| +|`attributes` | List of `Attribute`| The list of attributes.| + + +### Attribute attributes + +|Name|Type|Description| +|-|-|-| +|`label` | `Attrname` | The attribute machine-readable name.| +|`title` | `String` | The attribute human-readable title.| +|`description` | `Text` | The attribute description.| +|`datatype` | `Datatype` | The attribute datatype.| +|`cardinality` | `Cardinality` | The attribute cardinality (either `1` or `n`).| +*** + +Note that meanwhile there is no schema evolution, `log-size` doesn't affect +the result. + +*** +**EXAMPLE:** + +```http +GET /schema HTTP/1.1 +Host: approved-open-standard-guidance.register.gov.uk +Accept: application/json +``` + +```http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "attributes": [ + { + "label": "name", + "title": "Name", + "description": "The commonly-used name of a record.", + "datatype": "string", + "cardinality": "1" + }, + { + "label": "approved-open-standards", + "title": "Approved open standards", + "description": "Open standards that have been approved by government technology.", + "datatype": "curie", + "cardinality": "n" + }, + { + "label": "website", + "title": "Website", + "description": "The website for a record.", + "datatype": "url", + "cardinality": "1" + }, + { + "label": "start-date", + "title": "Start date", + "description": "The date a record first became relevant to a register.", + "datatype": "datetime", + "cardinality": "1" + }, + { + "label": "end-date", + "title": "End date", + "description": "The date a record stopped being applicable.", + "datatype": "datetime", + "cardinality": "1" + }, + + ] +} +``` +*** From 356baf059af612585ed47e69dd137dd29c0c1757 Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Fri, 17 Aug 2018 17:09:37 +0100 Subject: [PATCH 2/6] Assign number 0015 Signed-off-by: Arnau Siches --- content/schema-resource/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/schema-resource/index.md b/content/schema-resource/index.md index 71ecf5f..0fb7f6e 100644 --- a/content/schema-resource/index.md +++ b/content/schema-resource/index.md @@ -1,7 +1,7 @@ --- -rfc: +rfc: 0015 start_date: 2018-02-09 -pr: +pr: openregister/registers-rfcs#28 status: draft --- From 7d43be1485925cd6d23f0c39df507c93f3a3a6c2 Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Fri, 9 Feb 2018 15:36:28 +0000 Subject: [PATCH 3/6] Start document for defining how to get the schema Signed-off-by: Arnau Siches --- content/schema-api/index.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 content/schema-api/index.md diff --git a/content/schema-api/index.md b/content/schema-api/index.md new file mode 100644 index 0000000..59f06c9 --- /dev/null +++ b/content/schema-api/index.md @@ -0,0 +1,25 @@ +--- +rfc: +start_date: 2018-02-09 +pr: +status: draft +--- + +# Schema API + +## Summary + +This RFC proposes a way to retrieve the schema of a Register via its REST API. + + +## Motivation + +Currently, the Registers REST API doesn't offer any mechanism to know the +schema for a given size of the Register. Although you can get the list of +fields via the `/register` endpoint you need to complement this information +with the Field register. + + +## Explanation + +TODO From d7223735cf42e4628f1613ae203459d06266ad9b Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Mon, 20 Aug 2018 09:11:16 +0100 Subject: [PATCH 4/6] Remove old schema-api Signed-off-by: Arnau Siches --- content/schema-api/index.md | 25 ------------------------- 1 file changed, 25 deletions(-) delete mode 100644 content/schema-api/index.md diff --git a/content/schema-api/index.md b/content/schema-api/index.md deleted file mode 100644 index 59f06c9..0000000 --- a/content/schema-api/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -rfc: -start_date: 2018-02-09 -pr: -status: draft ---- - -# Schema API - -## Summary - -This RFC proposes a way to retrieve the schema of a Register via its REST API. - - -## Motivation - -Currently, the Registers REST API doesn't offer any mechanism to know the -schema for a given size of the Register. Although you can get the list of -fields via the `/register` endpoint you need to complement this information -with the Field register. - - -## Explanation - -TODO From df6f61dfd7d92579e61d297bbfa2dd95d8f21113 Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Mon, 20 Aug 2018 09:17:05 +0100 Subject: [PATCH 5/6] Make explicit where datatypes are described Signed-off-by: Arnau Siches --- content/schema-resource/index.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/content/schema-resource/index.md b/content/schema-resource/index.md index 0fb7f6e..8d6107e 100644 --- a/content/schema-resource/index.md +++ b/content/schema-resource/index.md @@ -23,6 +23,9 @@ more the day the schema gets the ability to evolve. ## Explanation +Note: All datatypes mentioned in this RFC are defined by the specification. In +a few cases like `Cardinality` or `Datatype` it is described inline. + *** ### Endpoint @@ -48,10 +51,10 @@ GET /schema |Name|Type|Description| |-|-|-| -|`label` | `Attrname` | The attribute machine-readable name.| +|`label` | `Attrname` | The attribute machine-readable name. (`[a-z][a-z0-9-]*`)| |`title` | `String` | The attribute human-readable title.| |`description` | `Text` | The attribute description.| -|`datatype` | `Datatype` | The attribute datatype.| +|`datatype` | `Datatype` | The attribute datatype. (one of `curie`, `datetime`, `attrname`, `hash`, `integer`, `period`, `string`, `text`, `url`)| |`cardinality` | `Cardinality` | The attribute cardinality (either `1` or `n`).| *** From 6357928da45720724daa7a341833f74e783cb6fc Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Wed, 22 Aug 2018 10:49:04 +0100 Subject: [PATCH 6/6] Reject RFC0015 Signed-off-by: Arnau Siches --- content/schema-resource/index.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/content/schema-resource/index.md b/content/schema-resource/index.md index 8d6107e..81c9bdd 100644 --- a/content/schema-resource/index.md +++ b/content/schema-resource/index.md @@ -2,11 +2,17 @@ rfc: 0015 start_date: 2018-02-09 pr: openregister/registers-rfcs#28 -status: draft +status: rejected --- # Schema resource +This RFC has been rejected (see comments +https://github.com/openregister/registers-rfcs/pull/28). + +In summary, this resource doesn't fit well with the broader metadata stream of +work. Schema will be addressed in a future RFC. + ## Summary This RFC proposes a schema resource to describe the register set of attributes