Skip to content

Commit ca059d3

Browse files
lwjohnst86signekb
andauthored
docs: 📝 add Extensions to config guide (#159)
# Description Describe how to use extensions in the config guide. Needs an in-depth review. ## Checklist - [x] Formatted Markdown - [x] Ran `just run-all` --------- Co-authored-by: Signe Kirk Brødbæk <signebroedbaek@gmail.com>
1 parent c2a58e9 commit ca059d3

File tree

1 file changed

+58
-31
lines changed

1 file changed

+58
-31
lines changed

docs/guide/config.qmd

Lines changed: 58 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -11,18 +11,19 @@ are available:
1111
- `version`: The version of Data Package standard to check against.
1212
Defaults to `v2`.
1313
- `exclusions`: A list of checks to exclude.
14-
- `custom_checks`: The list of custom checks to run in addition to the
15-
checks defined in the standard.
14+
- `extensions`: A list of extensions, which are additional checks that
15+
supplement those specified by the Data Package standard.
1616
- `strict`: Whether to include "SHOULD" checks in addition to "MUST"
1717
checks. Defaults to `False`.
1818

1919
::: callout-important
2020
The Data Package standard uses language from [RFC
21-
2119](https://www.ietf.org/rfc/rfc2119.txt) to define its specifications.
22-
They use "MUST" for required properties and "SHOULD" for properties that
23-
should be included but are not strictly required. We try to match this
24-
language in `check-datapackage` by using the terms "MUST" and "SHOULD",
25-
though we also use "required" for "MUST" in our documentation.
21+
2119](https://www.ietf.org/rfc/rfc2119.txt) to define its
22+
specifications. They use "MUST" for required properties and "SHOULD" for
23+
properties that should be included but are not strictly required. We try
24+
to match this language in `check-datapackage` by using the terms "MUST"
25+
and "SHOULD", though we also use "required" for "MUST" in our
26+
documentation.
2627
:::
2728

2829
## Excluding checks
@@ -97,13 +98,18 @@ the package and resource properties, and the resource `path` doesn't
9798
point to a data file. However, as we have defined exclusions for all of
9899
these, the function will flag no issues.
99100

100-
## Adding custom checks
101+
## Adding extensions
101102

102-
It is possible to create custom checks in addition to the ones defined
103-
in the Data Package standard.
103+
It is possible to add checks in addition to the ones defined in the Data
104+
Package standard. We call these additional checks *extensions*. There
105+
are currently two types of extensions supported: `CustomCheck` and
106+
`RequiredCheck`. You can add as many `CustomCheck`s and `RequiredCheck`s
107+
to your `Config` as you want to fit your needs.
108+
109+
### Custom checks
104110

105111
Let's say your organisation only accepts Data Packages licensed under
106-
MIT. You can express this requirement in a `CustomCheck` as follows:
112+
MIT. You can express this `CustomCheck` as follows:
107113

108114
```{python}
109115
license_check = cdp.CustomCheck(
@@ -117,19 +123,12 @@ license_check = cdp.CustomCheck(
117123
)
118124
```
119125

120-
Here's a breakdown of what each argument does:
121-
122-
- `type`: An identifier for your custom check. This is what will show
123-
up in error messages and what you will use if you want to exclude
124-
your check. Each `CustomCheck` should have a unique `type`.
125-
- `jsonpath`: The location of the field or fields the custom check
126-
applies to, expressed in [JSON
127-
path](https://en.wikipedia.org/wiki/JSONPath) notation. This check
128-
applies to the `name` field of all package licenses.
129-
- `message`: The message that is shown when the check is violated.
130-
- `check`: A function that expresses the custom check. It takes the
131-
value at the `jsonpath` location as input and returns true if the
132-
check is met, false if it isn't.
126+
For more details on what each parameter means, see the
127+
[`CustomCheck`](/docs/reference/custom_check.qmd) documentation.
128+
Specific to this example, the `type` is setting the identifier of the
129+
check to `only-mit` and the `jsonpath` is indicating to only check the
130+
`name` property of each license in the `licenses` property of the Data
131+
Package.
133132

134133
To register your custom checks with the `check()` function, you add them
135134
to the `Config` object passed to the function:
@@ -157,22 +156,50 @@ package_properties = {
157156
],
158157
}
159158
160-
config = cdp.Config(custom_checks=[license_check])
159+
config = cdp.Config(extensions=cdp.Extensions(custom_checks=[license_check]))
161160
cdp.check(properties=package_properties, config=config)
162161
```
163162

164163
We can see that the custom check was applied: `check()` returned one
165164
issue flagging the first license attached to the Data Package.
166165

166+
### Required checks
167+
168+
You can also set specific properties in the `datapackage.json` file to
169+
be required, even when they aren't required by the Data Package standard
170+
with a `RequiredCheck`. For example, if you want to make the
171+
`description` field of Data Package a required field, you can define a
172+
`RequiredCheck` like this:
173+
174+
```{python}
175+
#| eval: false
176+
description_required = cdp.RequiredCheck(
177+
jsonpath="$.description",
178+
message="The 'description' field is required in the Data Package properties.",
179+
)
180+
```
181+
182+
See the [`RequiredCheck`](/docs/reference/required_check.qmd)
183+
documentation for more details on its parameters.
184+
185+
To apply this `RequiredCheck`, it should be added to the `Config` object
186+
passed to `check()` like shown below:
187+
188+
```{python}
189+
#| eval: false
190+
config = cdp.Config(extensions=cdp.Extensions(required_checks=[description_required]))
191+
cdp.check(properties=package_properties, config=config)
192+
```
193+
167194
## Strict mode
168195

169196
The Data Package standard includes properties that "MUST" and "SHOULD"
170-
be included and/or have a specific format in a compliant Data Package. By default, `check()` only
171-
the `check()` function only includes "MUST" checks. To include "SHOULD" checks,
172-
set the `strict` argument to `True`. For example,
173-
the `name` field of a Data Package "SHOULD" not contain special
174-
characters. So running `check()` in strict mode (`strict=True`) on the following
175-
properties would output an issue.
197+
be included and/or have a specific format in a compliant Data Package.
198+
By default, `check()` only the `check()` function only includes "MUST"
199+
checks. To include "SHOULD" checks, set the `strict` argument to `True`.
200+
For example, the `name` field of a Data Package "SHOULD" not contain
201+
special characters. So running `check()` in strict mode (`strict=True`)
202+
on the following properties would output an issue.
176203

177204
```{python}
178205
#| eval: false

0 commit comments

Comments
 (0)