@@ -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
2020The 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
9798point to a data file. However, as we have defined exclusions for all of
9899these, 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
105111Let'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}
109115license_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
134133To register your custom checks with the ` check() ` function, you add them
135134to 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]) )
161160cdp.check(properties=package_properties, config=config)
162161```
163162
164163We can see that the custom check was applied: ` check() ` returned one
165164issue 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
169196The 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