From baba921edc331e60befdfb31addffb84b3e18c7e Mon Sep 17 00:00:00 2001 From: Kyle Husmann Date: Wed, 21 Aug 2024 13:41:19 -0700 Subject: [PATCH 01/11] first pass on category table recipe --- content/docs/recipes/category-tables.md | 80 +++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 content/docs/recipes/category-tables.md diff --git a/content/docs/recipes/category-tables.md b/content/docs/recipes/category-tables.md new file mode 100644 index 00000000..4dd9e31e --- /dev/null +++ b/content/docs/recipes/category-tables.md @@ -0,0 +1,80 @@ +--- +title: Category Tables +--- + + + + + + +
AuthorsKyle Husmann, Jan van der Laan, Albert-Jan, Phil Schumm
+ +Category Table Resources are Tabular Data Resources that can be referenced in the `categories` property of field definitions. This is useful when there are many (e.g. thousands) of categorical levels, the same `categories` definitions are repeated across many fields, or the categorical levels include a signficant amount of additional metadata. + +## Specification + +The Category Table Resource builds directly on the Tabular Data Resource specification. Thus a Category Table Resource `MUST` be a Tabular Data Resource and conform to the [Tabular Data Resource specification](/standard/data-resource/#tabular). + +The Category Table Resource has the following requirements over and above those imposed by Tabular Data Resource: + +- It `MUST` have a `type` property with the value `category-table`. + +- There `MUST` be a `valueField` property of type `string` that specifies the name of the field in the table that contains the values for the categories defined in the table. The field indicated by `valueField` `MUST` exist in the table and be of field type `string` or `integer`. + +- There `MAY` be an optional `labelField` property of type `string` that specificies the name of the field in the table that contains the labels for the categories defined in the table. When specified, the field indicated by `labelField` `MUST` exist in the table and be of field type `string`. + +- There `MAY` be an optional `categoriesOrdered` field of type `boolean`. When `categoriesOrdered` is `true`, implementations `SHOULD` regard the order of appearance of the values in the Category Table Resource as their natural order. When `false` implementations `SHOULD` assume that the categories do not have a natural order; when the property is not present, no assumption about the ordered nature of the values `SHOULD` be made. + +For example, the following is a valid Category Table Resource:: + +```json +{ + "name": "fruit-codes", + "type": "category-table", + "valueField": "code", + "labelField": "name", + "categoriesOrdered": false, + "schema": { + "fields": [ + { "name": "code", "type": "string" }, + { "name": "name", "type": "string" } + ] + }, + "data": [ + { "code": "A", "name": "Apple" }, + { "code": "B", "name": "Banana" }, + { "code": "C", "name": "Cherry" } + ] +} +``` + +## Usage + +Category Table Resources can be referenced by name in `categories` properties of field definitions. For example, the following is a valid field definition that references the `fruit-codes` Category Table Resource: + +```json +{ + "name": "fruit", + "type": "string", + "categories": "fruit-codes" +} +``` + +As with the [External Foreign Keys](/recipes/external-foreign-keys/) recipe, references to Category Table Resources in external packages can be made by providing the `categories` property an object with a `package` and `resource` property, both required `string`s. For example: + +```json +{ + "name": "fruit", + "type": "string", + "categories": { + "package": "http://example.com/package.json", + "resource": "fruit-codes" + } +} +``` + +## Constraints + +In a Category Table Resource, the field referenced by the `valueField` property `MUST` validated with `"required": true` and `"unique": true` field constraints. Similarly, when `labelField` is specified, the field it references `MUST` be of type `string` and be validated with the `"unique": true` field constraint. + +Fields referencing a Category Table Resource via the `categories` property `MUST` be of a type that matches the `valueField` type of the Category Table Resource. From 910ba75f5e9191d2d6520351b9e055c6ee8e2a6e Mon Sep 17 00:00:00 2001 From: Kyle Husmann Date: Mon, 14 Oct 2024 19:31:40 -0700 Subject: [PATCH 02/11] change to categoryFieldMap --- content/docs/recipes/category-tables.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/content/docs/recipes/category-tables.md b/content/docs/recipes/category-tables.md index 4dd9e31e..193006b2 100644 --- a/content/docs/recipes/category-tables.md +++ b/content/docs/recipes/category-tables.md @@ -15,25 +15,26 @@ Category Table Resources are Tabular Data Resources that can be referenced in th The Category Table Resource builds directly on the Tabular Data Resource specification. Thus a Category Table Resource `MUST` be a Tabular Data Resource and conform to the [Tabular Data Resource specification](/standard/data-resource/#tabular). -The Category Table Resource has the following requirements over and above those imposed by Tabular Data Resource: +In addition to the requirements of the Tabular Data Resource, Category Table Resources MUST have an additional +`categoryFieldMap` property of type `object` with the following properties: -- It `MUST` have a `type` property with the value `category-table`. +- There `MUST` be a `value` property of type `string` that specifies the name of the field in the table that contains the values for the categories defined in the table. The field indicated by `value` `MUST` exist in the table and be of field type `string` or `integer`. -- There `MUST` be a `valueField` property of type `string` that specifies the name of the field in the table that contains the values for the categories defined in the table. The field indicated by `valueField` `MUST` exist in the table and be of field type `string` or `integer`. +- There `MAY` be an optional `label` property of type `string` that specificies the name of the field in the table that contains the labels for the categories defined in the table. When specified, the field indicated by `label` `MUST` exist in the table and be of field type `string`. -- There `MAY` be an optional `labelField` property of type `string` that specificies the name of the field in the table that contains the labels for the categories defined in the table. When specified, the field indicated by `labelField` `MUST` exist in the table and be of field type `string`. +- There `MAY` be an optional `ordered` field of type `boolean`. When `ordered` is `true`, implementations `SHOULD` regard the order of appearance of the values in the Category Table Resource as their natural order. When `false` implementations `SHOULD` assume that the categories do not have a natural order; when the property is not present, no assumption about the ordered nature of the values `SHOULD` be made. -- There `MAY` be an optional `categoriesOrdered` field of type `boolean`. When `categoriesOrdered` is `true`, implementations `SHOULD` regard the order of appearance of the values in the Category Table Resource as their natural order. When `false` implementations `SHOULD` assume that the categories do not have a natural order; when the property is not present, no assumption about the ordered nature of the values `SHOULD` be made. - -For example, the following is a valid Category Table Resource:: +For example, the following is a valid Category Table Resource: ```json { "name": "fruit-codes", - "type": "category-table", - "valueField": "code", - "labelField": "name", - "categoriesOrdered": false, + "type": "table", + "categoryFieldMap": { + "value": "code", + "label": "name", + "ordered": false + }, "schema": { "fields": [ { "name": "code", "type": "string" }, From 0a960a998d9753dcbfd2994f36e46af1478aa8f3 Mon Sep 17 00:00:00 2001 From: Kyle Husmann Date: Mon, 14 Oct 2024 19:32:00 -0700 Subject: [PATCH 03/11] add internationalization section for category tables --- content/docs/recipes/category-tables.md | 32 ++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/content/docs/recipes/category-tables.md b/content/docs/recipes/category-tables.md index 193006b2..e6d0169a 100644 --- a/content/docs/recipes/category-tables.md +++ b/content/docs/recipes/category-tables.md @@ -78,4 +78,34 @@ As with the [External Foreign Keys](/recipes/external-foreign-keys/) recipe, ref In a Category Table Resource, the field referenced by the `valueField` property `MUST` validated with `"required": true` and `"unique": true` field constraints. Similarly, when `labelField` is specified, the field it references `MUST` be of type `string` and be validated with the `"unique": true` field constraint. -Fields referencing a Category Table Resource via the `categories` property `MUST` be of a type that matches the `valueField` type of the Category Table Resource. +Fields referencing a Category Table Resource via the `categories` property `MUST` be of a type that matches the `value` type of the Category Table Resource. + +## Internationalization + +Alternate transations of the category labels can be provided by way of the [Language Support](/recipes/language-support) recipe. The following example shows how the fruit-codes table from the previous example could be extended to support multiple languages: + +```json +{ + "name": "fruit-codes", + "type": "table", + "languages": ["en", "nl"], + "categoryFieldMap": { + "value": "code", + "label": "name", + "ordered": false + }, + "languages": ["en", "nl"], + "schema": { + "fields": [ + { "name": "code", "type": "string" }, + { "name": "name", "type": "string" }, + { "name": "name@nl", "type": "string" } + ] + }, + "data": [ + { "code": "A", "name": "Apple", "name@nl": "Appel" }, + { "code": "B", "name": "Banana", "name@nl": "Banaan" }, + { "code": "C", "name": "Cherry", "name@nl": "Kers" } + ] +} +``` From 131c2eeec899d870de7b00724208ce360f90b01e Mon Sep 17 00:00:00 2001 From: Kyle Husmann Date: Mon, 14 Oct 2024 19:38:39 -0700 Subject: [PATCH 04/11] add albert-jan's last name --- content/docs/recipes/category-tables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/recipes/category-tables.md b/content/docs/recipes/category-tables.md index e6d0169a..f54e4e81 100644 --- a/content/docs/recipes/category-tables.md +++ b/content/docs/recipes/category-tables.md @@ -5,7 +5,7 @@ title: Category Tables - +
AuthorsKyle Husmann, Jan van der Laan, Albert-Jan, Phil SchummKyle Husmann, Jan van der Laan, Albert-Jan Roskam, Phil Schumm
From ecb23f3f3a07ea34a66a7e92f9c397bba8d5ec71 Mon Sep 17 00:00:00 2001 From: Kyle Husmann Date: Tue, 15 Oct 2024 09:58:10 -0700 Subject: [PATCH 05/11] remove duplicate languages property --- content/docs/recipes/category-tables.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/docs/recipes/category-tables.md b/content/docs/recipes/category-tables.md index f54e4e81..d174962b 100644 --- a/content/docs/recipes/category-tables.md +++ b/content/docs/recipes/category-tables.md @@ -94,7 +94,6 @@ Alternate transations of the category labels can be provided by way of the [Lang "label": "name", "ordered": false }, - "languages": ["en", "nl"], "schema": { "fields": [ { "name": "code", "type": "string" }, From c450bb7a353e79c25615bcd9dba1d7cd76c3286c Mon Sep 17 00:00:00 2001 From: Phil Schumm Date: Mon, 9 Dec 2024 16:35:01 -0600 Subject: [PATCH 06/11] Update category-tables.md A few minor suggested edits, primarily for clarity. --- content/docs/recipes/category-tables.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/content/docs/recipes/category-tables.md b/content/docs/recipes/category-tables.md index d174962b..c31bd4c2 100644 --- a/content/docs/recipes/category-tables.md +++ b/content/docs/recipes/category-tables.md @@ -9,20 +9,20 @@ title: Category Tables -Category Table Resources are Tabular Data Resources that can be referenced in the `categories` property of field definitions. This is useful when there are many (e.g. thousands) of categorical levels, the same `categories` definitions are repeated across many fields, or the categorical levels include a signficant amount of additional metadata. +Category Table Resources are Tabular Data Resources that can be referenced in the `categories` property of a field descriptor. This is useful when there are many (e.g., thousands) of categorical levels (e.g., as with controlled vocabularies such as Medical Subject Headings (MeSH)), the same `categories` definitions are repeated across many fields (e.g., the same Likert scale applied to a series of items), or the categorical levels include a signficant amount of additional metadata (e.g., a hierarchical ontology such as the International Classification of Diseases (ICD)). Category Table Resources may be shared across data packages to facilitate harmonization, and provide support for categorical variables (e.g., as in Pandas, R, or Julia) or value labels (e.g., as in Stata, SAS, or SPSS). ## Specification -The Category Table Resource builds directly on the Tabular Data Resource specification. Thus a Category Table Resource `MUST` be a Tabular Data Resource and conform to the [Tabular Data Resource specification](/standard/data-resource/#tabular). +The Category Table Resource builds directly on the Tabular Data Resource specification. A Category Table Resource `MUST` be a Tabular Data Resource and conform to the [Tabular Data Resource specification](/standard/data-resource/#tabular). -In addition to the requirements of the Tabular Data Resource, Category Table Resources MUST have an additional +In addition to the requirements of a Tabular Data Resource, Category Table Resources MUST have an additional `categoryFieldMap` property of type `object` with the following properties: -- There `MUST` be a `value` property of type `string` that specifies the name of the field in the table that contains the values for the categories defined in the table. The field indicated by `value` `MUST` exist in the table and be of field type `string` or `integer`. +- There `MUST` be a `value` property of type `string` that specifies the name of the field in the Category Table Resource containing the values for the categories as they would appear in a focal data resource. The field indicated by `value` `MUST` exist in the Category Table Resource and be of field type `string` or `integer`. -- There `MAY` be an optional `label` property of type `string` that specificies the name of the field in the table that contains the labels for the categories defined in the table. When specified, the field indicated by `label` `MUST` exist in the table and be of field type `string`. +- There `MAY` be an optional `label` property of type `string` that specificies the name of the field in the Category Table Resource containing labels for the categories. When specified, the field indicated by `label` `MUST` exist in the Category Table Resource and be of field type `string`. -- There `MAY` be an optional `ordered` field of type `boolean`. When `ordered` is `true`, implementations `SHOULD` regard the order of appearance of the values in the Category Table Resource as their natural order. When `false` implementations `SHOULD` assume that the categories do not have a natural order; when the property is not present, no assumption about the ordered nature of the values `SHOULD` be made. +- There `MAY` be an optional `ordered` property of type `boolean`. When `ordered` is `true`, implementations `SHOULD` regard the order of appearance of the values in the Category Table Resource as their natural order. When `false` implementations `SHOULD` assume that the categories do not have a natural order. When the property is not present, no assumption about the ordered nature of the values `SHOULD` be made. For example, the following is a valid Category Table Resource: @@ -51,7 +51,7 @@ For example, the following is a valid Category Table Resource: ## Usage -Category Table Resources can be referenced by name in `categories` properties of field definitions. For example, the following is a valid field definition that references the `fruit-codes` Category Table Resource: +Category Table Resources can be referenced by name in the `categories` property of a field definition in a Tabular Data Resource. For example, the following is a valid field definition that references the `fruit-codes` Category Table Resource defined above: ```json { @@ -61,7 +61,7 @@ Category Table Resources can be referenced by name in `categories` properties of } ``` -As with the [External Foreign Keys](/recipes/external-foreign-keys/) recipe, references to Category Table Resources in external packages can be made by providing the `categories` property an object with a `package` and `resource` property, both required `string`s. For example: +As with the [External Foreign Keys](/recipes/external-foreign-keys/) recipe, references to Category Table Resources in external packages can be made by specifying the `categories` property as an object with a `package` and `resource` property, both required to be of type `string`. For example: ```json { @@ -78,7 +78,7 @@ As with the [External Foreign Keys](/recipes/external-foreign-keys/) recipe, ref In a Category Table Resource, the field referenced by the `valueField` property `MUST` validated with `"required": true` and `"unique": true` field constraints. Similarly, when `labelField` is specified, the field it references `MUST` be of type `string` and be validated with the `"unique": true` field constraint. -Fields referencing a Category Table Resource via the `categories` property `MUST` be of a type that matches the `value` type of the Category Table Resource. +Fields in a focal data resource referencing a Category Table Resource via the `categories` property `MUST` have a type identical to the type of the corresponding `value` field in the Category Table Resource. ## Internationalization From 99434834285d72185a48398bd5fe7582ed94e42f Mon Sep 17 00:00:00 2001 From: Kyle Husmann Date: Tue, 15 Oct 2024 10:50:09 -0700 Subject: [PATCH 07/11] add edits after categorical working group meeting --- content/docs/recipes/category-tables.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/content/docs/recipes/category-tables.md b/content/docs/recipes/category-tables.md index c31bd4c2..aa17cfbf 100644 --- a/content/docs/recipes/category-tables.md +++ b/content/docs/recipes/category-tables.md @@ -61,7 +61,7 @@ Category Table Resources can be referenced by name in the `categories` property } ``` -As with the [External Foreign Keys](/recipes/external-foreign-keys/) recipe, references to Category Table Resources in external packages can be made by specifying the `categories` property as an object with a `package` and `resource` property, both required to be of type `string`. For example: +As with the [External Foreign Keys](/recipes/external-foreign-keys/) recipe, references to Category Table Resources in external packages can be made by providing the `categories` property an object with a `package` and `resource` property, both of type `string`. For example: ```json { @@ -74,15 +74,25 @@ As with the [External Foreign Keys](/recipes/external-foreign-keys/) recipe, ref } ``` +When `package` is omitted, implementations `SHOULD` assume resource references the current data package. The `resource` property `MUST` be a valid Category Table Resource name in the referenced package. + ## Constraints -In a Category Table Resource, the field referenced by the `valueField` property `MUST` validated with `"required": true` and `"unique": true` field constraints. Similarly, when `labelField` is specified, the field it references `MUST` be of type `string` and be validated with the `"unique": true` field constraint. +In a Category Table Resource, the field referenced by the `value` property `MUST` validated with `"required": true` and `"unique": true` field constraints. Similarly, when `label` is specified, the field it references `MUST` be of type `string` and be validated with the `"unique": true` field constraint. + +Fields in a focal data resource referencing a Category Table Resource via the `categories` property `MUST` have a type identical to the type of the corresponding `value` field in the Category Table Resource. For example, the following is an invalid references to the `fruit-codes` Category Table Resource because the `type` of the categorical field being defined is `integer` while the `value` field in the `fruit-codes` Category Table Resource is of type `string`: -Fields in a focal data resource referencing a Category Table Resource via the `categories` property `MUST` have a type identical to the type of the corresponding `value` field in the Category Table Resource. +```json +{ + "name": "fruit", + "type": "integer", + "categories": "fruit-codes" +} +``` ## Internationalization -Alternate transations of the category labels can be provided by way of the [Language Support](/recipes/language-support) recipe. The following example shows how the fruit-codes table from the previous example could be extended to support multiple languages: +Alternate translations of the category labels can be provided by way of the [Language Support](/recipes/language-support) recipe. The following example shows how the fruit-codes table from the previous example could be extended to support multiple languages: ```json { From a5c3ffc2fa6512cf021fffc08e008dba19002eaa Mon Sep 17 00:00:00 2001 From: Kyle Husmann Date: Sun, 12 Jan 2025 13:15:13 -0800 Subject: [PATCH 08/11] add encodedAs property; remove categories shortcut --- content/docs/recipes/category-tables.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/content/docs/recipes/category-tables.md b/content/docs/recipes/category-tables.md index aa17cfbf..31803277 100644 --- a/content/docs/recipes/category-tables.md +++ b/content/docs/recipes/category-tables.md @@ -51,17 +51,27 @@ For example, the following is a valid Category Table Resource: ## Usage -Category Table Resources can be referenced by name in the `categories` property of a field definition in a Tabular Data Resource. For example, the following is a valid field definition that references the `fruit-codes` Category Table Resource defined above: +Category Table Resources are used by providing the `categories` property of a categorical field descriptor with an `object` with the following properties: + +- There `MUST` be a `resource` property of type `string` that specifies the name of the Category Table Resource to be used. + +- There `MAY` be an optional `package` property of type `string` that specifies the package containing the Category Table Resource to be used. As with the [External Foreign Keys](/recipes/external-foreign-keys/) recipe, the `package` property `MUST` be either a fully qualified HTTP address to a Data Package `datapackage.json` file or a data package name that can be resolved by a canonical data package registry. If omitted, implementations `SHOULD` assume the Category Table Resource is in the current data package. + +- There `MAY` be an optional `encodedAs` property of type `string` that specifies whether the values of the focal categorical field reference the `value` or `label` field of the Category Table Resource. When `encodedAs` is `"value"`, the values of the focal categorical field are mapped to the values of the `value` field in the Category Table Resource. When `encodedAs` is `"label"`, the values of the focal categorical field are mapped to the values of the `label` field in the Category Table Resource. When `encodedAs` is omitted, implementations `SHOULD` assume the values of the categorical field are the values of the `value` field in the Category Table Resource. + +For example, the following field definition references the `fruit-codes` Category Table Resource defined above if it was in the same data package used the `value`s of the Category Table Resource (in this case, the `code` field of `fruit-codes`): ```json { "name": "fruit", "type": "string", - "categories": "fruit-codes" + "categories": { + "resource": "fruit-codes" + } } ``` -As with the [External Foreign Keys](/recipes/external-foreign-keys/) recipe, references to Category Table Resources in external packages can be made by providing the `categories` property an object with a `package` and `resource` property, both of type `string`. For example: +Alternatively, if the `fruit-codes` Category Table Resource was in an external data package and used the Category Table Resource's `label`s to represent the field's options (in this case, the `name` field of `fruit-codes`), the field definition would be: ```json { @@ -69,13 +79,12 @@ As with the [External Foreign Keys](/recipes/external-foreign-keys/) recipe, ref "type": "string", "categories": { "package": "http://example.com/package.json", - "resource": "fruit-codes" + "resource": "fruit-codes", + "encodedAs": "label" } } ``` -When `package` is omitted, implementations `SHOULD` assume resource references the current data package. The `resource` property `MUST` be a valid Category Table Resource name in the referenced package. - ## Constraints In a Category Table Resource, the field referenced by the `value` property `MUST` validated with `"required": true` and `"unique": true` field constraints. Similarly, when `label` is specified, the field it references `MUST` be of type `string` and be validated with the `"unique": true` field constraint. From 13e227ed8b097d858db6ee2022c92c5fee89e002 Mon Sep 17 00:00:00 2001 From: Jan van der Laan Date: Tue, 4 Feb 2025 16:59:51 +0100 Subject: [PATCH 09/11] Added discussion section to category table recipe --- content/docs/recipes/category-tables.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/content/docs/recipes/category-tables.md b/content/docs/recipes/category-tables.md index 31803277..6cc3df78 100644 --- a/content/docs/recipes/category-tables.md +++ b/content/docs/recipes/category-tables.md @@ -127,3 +127,24 @@ Alternate translations of the category labels can be provided by way of the [Lan ] } ``` + + +## Discussion + +Being able to define lists of categories in a separate data resource has a number of advantages: + +- In case of a large number of categories it is often easier to maintain these in files, such as CSV files. This also keeps the `datapackage.json` file compact and readable for humans. + +- The data set in the category table resource can store additional information besides the 'value' and 'label'. For example, the categories could have descriptions or the categories could form a hierarchy. + +- It is also possible to store additional meta data in the category table resource. For example, it is possible to indicate the source, license, version and owner of the data resource. This is important for many 'official' categories lists where there can be many similar versions maintained by different organisations. + +- When different fields use the same categories they can all refer to the same category table resource. First, this allows to reuse of the categories. Second, by referring to the same data resource, the field descriptors can indicate that the categories are comparable between fields. + +- It is possible to refer to category table resources in other data packages. This makes it, for example, possible to create centrally maintained repositories of categories. + +It is assumed that the category table resource, is a tabular data resource. However, any data format that has some tabular structure -- has a 'value' and 'label' field -- can be used to store the categories. This also allows implementers to support other data types than just CSV. + +One such example is [SDMX](https://sdmx.org/). SDMX is used by many statistical agencies to disseminate their data. SDMX has the concept of CodeList which serves the same purpose as the 'categories' field of the field descriptor. A CodeList has a tabular structure where each code consists of an 'id' and 'name' (names can be multilingual), which correspond to 'value' and 'label' respectively. Therefore, it is possible to refer to an SDMX CodeList from a Category Table Resource. + + From 15ac3fea73db60ab20465cfbdca1e7d94495c173 Mon Sep 17 00:00:00 2001 From: Kyle Husmann Date: Tue, 4 Feb 2025 20:13:33 -0800 Subject: [PATCH 10/11] remove note on non-tabular category table resources (for now) --- content/docs/recipes/category-tables.md | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/content/docs/recipes/category-tables.md b/content/docs/recipes/category-tables.md index 6cc3df78..1e9b96cb 100644 --- a/content/docs/recipes/category-tables.md +++ b/content/docs/recipes/category-tables.md @@ -128,7 +128,6 @@ Alternate translations of the category labels can be provided by way of the [Lan } ``` - ## Discussion Being able to define lists of categories in a separate data resource has a number of advantages: @@ -139,12 +138,6 @@ Being able to define lists of categories in a separate data resource has a numbe - It is also possible to store additional meta data in the category table resource. For example, it is possible to indicate the source, license, version and owner of the data resource. This is important for many 'official' categories lists where there can be many similar versions maintained by different organisations. -- When different fields use the same categories they can all refer to the same category table resource. First, this allows to reuse of the categories. Second, by referring to the same data resource, the field descriptors can indicate that the categories are comparable between fields. - -- It is possible to refer to category table resources in other data packages. This makes it, for example, possible to create centrally maintained repositories of categories. - -It is assumed that the category table resource, is a tabular data resource. However, any data format that has some tabular structure -- has a 'value' and 'label' field -- can be used to store the categories. This also allows implementers to support other data types than just CSV. - -One such example is [SDMX](https://sdmx.org/). SDMX is used by many statistical agencies to disseminate their data. SDMX has the concept of CodeList which serves the same purpose as the 'categories' field of the field descriptor. A CodeList has a tabular structure where each code consists of an 'id' and 'name' (names can be multilingual), which correspond to 'value' and 'label' respectively. Therefore, it is possible to refer to an SDMX CodeList from a Category Table Resource. - +- When different fields use the same categories they can all refer to the same category table resource. First, this allows to reuse of the categories. Second, by referring to the same data resource, the field descriptors can indicate that the categories are comparable between fields. +- It is possible to refer to category table resources in other data packages. This makes it, for example, possible to create centrally maintained repositories of categories. From 439f1457686f394cf322f3c6b75d3f69bef2be04 Mon Sep 17 00:00:00 2001 From: Kyle Husmann Date: Wed, 5 Feb 2025 19:26:07 -0800 Subject: [PATCH 11/11] fix unspecified resource in categories reference --- content/docs/recipes/category-tables.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/docs/recipes/category-tables.md b/content/docs/recipes/category-tables.md index 1e9b96cb..9c7de600 100644 --- a/content/docs/recipes/category-tables.md +++ b/content/docs/recipes/category-tables.md @@ -95,7 +95,9 @@ Fields in a focal data resource referencing a Category Table Resource via the `c { "name": "fruit", "type": "integer", - "categories": "fruit-codes" + "categories": { + "resource": "fruit-codes" + } } ```