From 0777fbd8fb95fda6f267d9a7291b7351a8bf7d0d Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Thu, 29 Mar 2018 15:30:10 +0100 Subject: [PATCH 1/4] Add reference consolidation RFC describing the two mechanisms for linking registers and the proposal to use CURIEs from now on. Signed-off-by: Arnau Siches --- content/reference-strategy/index.md | 141 ++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 content/reference-strategy/index.md diff --git a/content/reference-strategy/index.md b/content/reference-strategy/index.md new file mode 100644 index 0000000..4a8fbae --- /dev/null +++ b/content/reference-strategy/index.md @@ -0,0 +1,141 @@ +--- +rfc: +start_date: 2018-03-29 +pr: +status: draft +--- + +# Reference strategy + +## Summary + +This RFC proposes CURIEs as the only way to reference between records and from a record +to a register (set of records). It can be seen as the natural consequence of +[RFC 0002: URI Consolidation](https://github.com/openregister/registers-rfcs/blob/master/content/uri-consolidation/index.md). + +Note that other types of references (e.g. subset of records) are out of the +scope. See the discussion [Group References](https://github.com/openregister/registers-rfcs/issues/4) +for more on this. + +## Motivation + +Currently, there are two mechanisms for referencing: a foreign key and a CURIE. + +### Foreign Key + +A foreign key is a regular string that _happens_ to be an identifier in another +register (including itself). You have to deduce by the name of the field that +the values are in fact identifiers (primary keys) for records in a Register of +the same name. To get the URI of the referenced resource you have to: + +1. Given a fieldname `country` +1. And a value `GB` +1. Compose a register subdomain: `country.register.gov.uk` +1. Compose a record set URI: `https://country.register.gov.uk/records/` +1. Concatenate the URI with the value: `https://country.register.gov.uk/records/GB` + +There is a special case here where a foreign key refers to a register register +record. Then the meaning of the relation is “everything in the register +described by the linked record”. + +1. Given a fieldname `register` +1. And a value `country` +1. Compose a register subdomain: `country.register.gov.uk` +1. Compose a set URI: `https://country.register.gov.uk/records/` + +#### Benefits + +* Potentially familiar to people familiar with the Relational Data Model. +* Hints a single type of thing for any value in the field. + +#### Problems + +* To know a field contains a foreign key, you need to look up the register field +in the field definition. If it is informed, the datatype is not “string” but +“key”. +* Only able to reference one register per field. +* Linking a full set of records is a special case. + + +### CURIE + +A [CURIE](https://www.w3.org/TR/curie/) is a Compact URI so according to its +definition for a given CURIE should be able to be transformed into its +expanded URI form. The current use of CURIEs lacks any mechanism to resolve the +prefix into its equivalent URL which means the expansion mechanism relies on +the assumption that the prefix will be a known Register identifier, so to +expand it you have to: + +1. Given a CURIE `country:GB` +1. Take its prefix: `country` +1. Compose a register subdomain: `country.register.gov.uk` +1. Compose a record URI: `https://country.register.gov.uk/records/` +1. Concatenate the URI with the CURIE value: `https://country.register.gov.uk/records/GB` + +In the case of a CURIE to the full set of records you don't need the last +step: + +1. Given a CURIE `country:` +1. Take its prefix: `country` +1. Compose a register subdomain: `country.register.gov.uk` +1. Compose a record URI: `https://country.register.gov.uk/records/` + + +#### Benefits + +* Allows a field to reference a Record in any known register. +* A data consumer can know the field contains references by the datatype of the + field. +* It's built on a existing open standard. Technically it is a note and not a + recommendation but it is used in many standards, including RDF. + +#### Problems + +* A consumer has to know the assumptions that lead from a prefix to a URI. And + know it's not the standard way to work with CURIEs. +* It's not possible to infer a type constraint for any new value. + + +## Explanation + +Although Registers could be built on any of the exposed solutions, a CURIE has +the edge in flexibility and builds on top of existing open standards for +linking resources. + +### Expanding a CURIE + +The current solution for expanding CURIEs relies on a few assumptions. In +order to remove this RFC proposes providing a **Context**, in a similar way +[JSON-LD](https://json-ld.org/) does it. + +The definition of the context will happen at the Register Environment level, +this way it can be guaranteed that a single context will work for any Register +part of the Environment. + +A Context is a dictionary of prefixes and URIs, in JSON it would look like: + +```json +{ + "country": "https://country.register.gov.uk/records/", + "lae": "https://local-authority-eng.register.gov.uk/records/", + "example": "https://example.org/" +} +``` + +With this context, the following expansions are expected to be true: + +* `country:GB` -> `https://country.register.gov.uk/records/GB` +* `country:ZZ` -> `https://country.register.gov.uk/records/ZZ` +* `lae:BIR` -> `https://local-authority-eng.register.gov.uk/records/BIR` +* `example:32` -> `https://example.org/32` + +Note that currently the context is managed partially by the Register register. +Further work is expected to evolve it to match this definition of context. + +## Conclusion + +This RFC accepts CURIE as the only mechanism for linking between register from +now on given they offer the flexibility required by registers. + +Existing registers that use foreign keys will be maintained to avoid +disruption in the registers ecosystem. From ed8b80456c4825ea320a4006387861dbc2d06187 Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Wed, 18 Jul 2018 09:27:00 +0100 Subject: [PATCH 2/4] Reword based on @michaelabenyohai suggestions Signed-off-by: Arnau Siches --- content/reference-strategy/index.md | 69 ++++++++++++++++++++--------- 1 file changed, 47 insertions(+), 22 deletions(-) diff --git a/content/reference-strategy/index.md b/content/reference-strategy/index.md index 4a8fbae..2d9eb40 100644 --- a/content/reference-strategy/index.md +++ b/content/reference-strategy/index.md @@ -13,9 +13,10 @@ This RFC proposes CURIEs as the only way to reference between records and from a to a register (set of records). It can be seen as the natural consequence of [RFC 0002: URI Consolidation](https://github.com/openregister/registers-rfcs/blob/master/content/uri-consolidation/index.md). -Note that other types of references (e.g. subset of records) are out of the -scope. See the discussion [Group References](https://github.com/openregister/registers-rfcs/issues/4) -for more on this. +Note that other types of references (e.g. subset of records) are out of scope. +See the discussion [Group +References](https://github.com/openregister/registers-rfcs/issues/4) for more +on this. ## Motivation @@ -28,33 +29,43 @@ register (including itself). You have to deduce by the name of the field that the values are in fact identifiers (primary keys) for records in a Register of the same name. To get the URI of the referenced resource you have to: -1. Given a fieldname `country` +1. Given a field with name `x`, where the record for `x` in the Field register + has the `register` field populated with value `country` 1. And a value `GB` 1. Compose a register subdomain: `country.register.gov.uk` 1. Compose a record set URI: `https://country.register.gov.uk/records/` 1. Concatenate the URI with the value: `https://country.register.gov.uk/records/GB` -There is a special case here where a foreign key refers to a register register -record. Then the meaning of the relation is “everything in the register -described by the linked record”. +There is a case that can be seen as a special case where a foreign key refers +to a register register record. Then the meaning of the relation can be seen as +“everything in the register described by the linked record”. 1. Given a fieldname `register` 1. And a value `country` -1. Compose a register subdomain: `country.register.gov.uk` -1. Compose a set URI: `https://country.register.gov.uk/records/` +1. Compose a register subdomain: `register.register.gov.uk` +1. Compose a record set URI: `https://register.register.gov.uk/records/` +1. Concatenate the URI with the value: `https://register.register.gov.uk/records/country` +1. Derive the record set URI: `https://country.register.gov.uk/records/` + +The last step is not specified anywhere so it is an internal convention more +than anything a regular user might know. It is defined here in order to mirror +the capabilities for CURIEs. #### Benefits * Potentially familiar to people familiar with the Relational Data Model. * Hints a single type of thing for any value in the field. -#### Problems +#### Limitations -* To know a field contains a foreign key, you need to look up the register field -in the field definition. If it is informed, the datatype is not “string” but -“key”. +* To know a field contains a foreign key, you need to look up the `register` + field in the field register. If it is informed, the original field is a “key” + of type defined in the `datatype` field. * Only able to reference one register per field. -* Linking a full set of records is a special case. +* You need a field for each register linked to even if they have the same type + of relationship with the record (e.g. owned by, managed by). +* Linking a full set of records is not possible. Although there is a + convention that could be standarised previous section. ### CURIE @@ -89,7 +100,7 @@ step: * It's built on a existing open standard. Technically it is a note and not a recommendation but it is used in many standards, including RDF. -#### Problems +#### Limitations * A consumer has to know the assumptions that lead from a prefix to a URI. And know it's not the standard way to work with CURIEs. @@ -132,10 +143,24 @@ With this context, the following expansions are expected to be true: Note that currently the context is managed partially by the Register register. Further work is expected to evolve it to match this definition of context. -## Conclusion - -This RFC accepts CURIE as the only mechanism for linking between register from -now on given they offer the flexibility required by registers. - -Existing registers that use foreign keys will be maintained to avoid -disruption in the registers ecosystem. +## Naming conventions + +Foreign keys have been using the same field definition as the primary key in +the targeted register. This means that a sigle entry in the field register +defines a field used in one register as the primary key and in another +register as a foreign key. This convention derives from another one where the +primary key field is always the same as the register identifier. E.g. the +register with id `country`, has a field `country` that acts as the primary key +for that register. Another register with a field `country` will use the field +as a foreign key. + +With CURIEs this assumption weakens. A future RFC will define the new +convention for naming fields of type CURIE although this will be _informative_ +not _normative_. The current thinking is to move away from using names and +start using relationships. For example, given a register with a link to the +organisation that manages the resource, it would use something like +`managed-by` instead of `manager` or `organisation`. + +A future RFC will formalise the way to explicitly identify the primary key for +a register so the convention of using the register identifier will be +addressed there. From 159b93a1e21f814345c9c12a4ae96dd0f29f2a4d Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Thu, 9 Aug 2018 13:21:09 +0100 Subject: [PATCH 3/4] Add RFC number Signed-off-by: Arnau Siches --- content/reference-strategy/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/reference-strategy/index.md b/content/reference-strategy/index.md index 2d9eb40..ce5d842 100644 --- a/content/reference-strategy/index.md +++ b/content/reference-strategy/index.md @@ -1,7 +1,7 @@ --- -rfc: +rfc: 0005 start_date: 2018-03-29 -pr: +pr: openregister/registers-rfcs#11 status: draft --- From ed6a2b09b5cf3a67b7eeee3aba3e3b83302abe41 Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Mon, 13 Aug 2018 13:58:11 +0100 Subject: [PATCH 4/4] Add decision date Signed-off-by: Arnau Siches --- content/reference-strategy/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/reference-strategy/index.md b/content/reference-strategy/index.md index ce5d842..99b30be 100644 --- a/content/reference-strategy/index.md +++ b/content/reference-strategy/index.md @@ -1,8 +1,9 @@ --- rfc: 0005 start_date: 2018-03-29 +decision_date: 2018-08-13 pr: openregister/registers-rfcs#11 -status: draft +status: approved --- # Reference strategy