From 1a661f470671cca4845f665324af2b30261fb8f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Mon, 13 Oct 2025 10:37:20 +0200 Subject: [PATCH 1/4] docs: :memo: update naming section --- docs/design/architecture.qmd | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/docs/design/architecture.qmd b/docs/design/architecture.qmd index 1207ff8a..94cf8f99 100644 --- a/docs/design/architecture.qmd +++ b/docs/design/architecture.qmd @@ -90,24 +90,20 @@ flowchart LR This section contains a naming scheme for `check-datapackage` that is inspired by the [Data Package standard](https://datapackage.org/). -Following Data Package terminology, we simplify "data package" to -"package" and "data resource" to "resource". The Data Package standard -calls a standalone and complete metadata structure -["descriptor"](https://datapackage.org/standard/glossary/#descriptor). -Descriptors are JSON objects contained in JSON files (e.g., -`datapackage.json` contains the Data Package descriptor). We adopt this -usage, but may also use the word "properties" to refer to the metadata -as a whole. +Overall, we follow the Data Package terminology where possible to keep +things consistent. However, we also introduce some new terms and +concepts specific to `check-datapackage`. The main objects and actions +used throughout the package can be found in the tables below. ### Objects | Object | Description | |----------------------------|--------------------------------------------| -| package | A Data Package that contains a collection of related data resources and properties. | +| package | A Data Package that contains a collection of related data resources and descriptor(s). | | resource | A single data file within a package including its properties. | -| descriptor | The standalone and complete metadata structure contained in a JSON file, for example, in `datapackage.json`. | -| properties | Individual elements of the metadata structure or the structure as a whole. | -| standard | The JSON schema defining the Data Package standard. | +| descriptor | A standalone and complete metadata structure contained in a JSON file, for example, in `datapackage.json`. | +| properties | Metadata fields (name-value pairs) of a descriptor loaded as a Python dictionary. This can be a subset of the original descriptor or the entire structure. | +| schema | The JSON schema defining the Data Package standard. | | config | An object containing settings for modifying the behaviour and output of the check mechanism. | : Objects used throughout `check-datapackage`. @@ -117,7 +113,7 @@ as a whole. | Action | Description | |----------------------------|--------------------------------------------| | check | Check that a descriptor conforms to the Data Package standard. | -| explain | Explain issues flagged by the check mechanism in more detail using non-technical language. | -| read | Read various files, such as the Data Package descriptor or configuration files. | +| explain | Explain issues flagged by the check action in more detail using non-technical language. | +| read | Read various files, such as a Data Package descriptor or a configuration file. | : Actions that `check-datapackage` can perform. From 63d99e81dce4b20d4e42d3ca2355aaed9212e608 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Mon, 13 Oct 2025 10:40:45 +0200 Subject: [PATCH 2/4] docs: :memo: move naming section up before c4 models --- docs/design/architecture.qmd | 65 ++++++++++++++++++------------------ 1 file changed, 33 insertions(+), 32 deletions(-) diff --git a/docs/design/architecture.qmd b/docs/design/architecture.qmd index 94cf8f99..232a8ece 100644 --- a/docs/design/architecture.qmd +++ b/docs/design/architecture.qmd @@ -29,6 +29,39 @@ This section describes the different users we expect and design for: add custom checks or ignore certain checks to fit the specific needs of the project. +## Naming + +This section contains a naming scheme for `check-datapackage` that is +inspired by the [Data Package standard](https://datapackage.org/). + +Overall, we follow the Data Package terminology where possible to keep +things consistent. However, we also introduce some new terms and +concepts specific to `check-datapackage`. The main objects and actions +used throughout the package can be found in the tables below. + +### Objects + +| Object | Description | +|----------------------------|--------------------------------------------| +| package | A Data Package that contains a collection of related data resources and descriptor(s). | +| resource | A single data file within a package including its properties. | +| descriptor | A standalone and complete metadata structure contained in a JSON file, for example, in `datapackage.json`. | +| properties | Metadata fields (name-value pairs) of a descriptor loaded as a Python dictionary. This can be a subset of the original descriptor or the entire structure. | +| schema | The JSON schema defining the Data Package standard. | +| config | An object containing settings for modifying the behaviour and output of the check mechanism. | + +: Objects used throughout `check-datapackage`. + +### Actions + +| Action | Description | +|----------------------------|--------------------------------------------| +| check | Check that a descriptor conforms to the Data Package standard. | +| explain | Explain issues flagged by the check action in more detail using non-technical language. | +| read | Read various files, such as a Data Package descriptor or a configuration file. | + +: Actions that `check-datapackage` can perform. + ## C4 Models This section contains the [C4 Models](https://c4model.com/) for @@ -85,35 +118,3 @@ flowchart LR in_dp_json --> check ``` -## Naming - -This section contains a naming scheme for `check-datapackage` that is -inspired by the [Data Package standard](https://datapackage.org/). - -Overall, we follow the Data Package terminology where possible to keep -things consistent. However, we also introduce some new terms and -concepts specific to `check-datapackage`. The main objects and actions -used throughout the package can be found in the tables below. - -### Objects - -| Object | Description | -|----------------------------|--------------------------------------------| -| package | A Data Package that contains a collection of related data resources and descriptor(s). | -| resource | A single data file within a package including its properties. | -| descriptor | A standalone and complete metadata structure contained in a JSON file, for example, in `datapackage.json`. | -| properties | Metadata fields (name-value pairs) of a descriptor loaded as a Python dictionary. This can be a subset of the original descriptor or the entire structure. | -| schema | The JSON schema defining the Data Package standard. | -| config | An object containing settings for modifying the behaviour and output of the check mechanism. | - -: Objects used throughout `check-datapackage`. - -### Actions - -| Action | Description | -|----------------------------|--------------------------------------------| -| check | Check that a descriptor conforms to the Data Package standard. | -| explain | Explain issues flagged by the check action in more detail using non-technical language. | -| read | Read various files, such as a Data Package descriptor or a configuration file. | - -: Actions that `check-datapackage` can perform. From 77ff5798eb04d02175989110bb849b641bc3faae Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 13 Oct 2025 08:48:08 +0000 Subject: [PATCH 3/4] chore(pre-commit): :pencil2: automatic fixes --- docs/design/architecture.qmd | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/design/architecture.qmd b/docs/design/architecture.qmd index 232a8ece..9deb5ce8 100644 --- a/docs/design/architecture.qmd +++ b/docs/design/architecture.qmd @@ -117,4 +117,3 @@ flowchart LR ext_dp_schema --> check in_dp_json --> check ``` - From 5ae69cfe2b7d6059ad84fe6eefeef093244c9f8d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Tue, 14 Oct 2025 10:10:36 +0200 Subject: [PATCH 4/4] docs: :fire: remove resource from object table Co-authored-by: Luke W. Johnston --- docs/design/architecture.qmd | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/design/architecture.qmd b/docs/design/architecture.qmd index 9deb5ce8..5edae4e3 100644 --- a/docs/design/architecture.qmd +++ b/docs/design/architecture.qmd @@ -44,7 +44,6 @@ used throughout the package can be found in the tables below. | Object | Description | |----------------------------|--------------------------------------------| | package | A Data Package that contains a collection of related data resources and descriptor(s). | -| resource | A single data file within a package including its properties. | | descriptor | A standalone and complete metadata structure contained in a JSON file, for example, in `datapackage.json`. | | properties | Metadata fields (name-value pairs) of a descriptor loaded as a Python dictionary. This can be a subset of the original descriptor or the entire structure. | | schema | The JSON schema defining the Data Package standard. |