docs: 📝 clarify MUST vs SHOULD terms

docs/design/architecture.qmd

@@ -76,11 +76,12 @@ interact with `check-datapackage`. This includes the user types and the
 Data Package standard.
 
 `check-datapackage` receives the definitions of the Data Package
-descriptor's structure---including required properties, their formats,
-and recommended fields---from the Data Package standard. The standard
-provides this information through versioned JSON Schema profiles that
-define required properties and textual descriptions that outline
-recommendations.
+descriptor's structure---including properties that [must or
+should](https://datapackage.org/standard/data-package/#language) be
+included and their formats---from the Data Package standard (version 2). The
+standard provides this information through versioned JSON Schema
+profiles that define required properties and textual descriptions that
+outline compliance.
 
 ::: callout-note
 In the initial version of `check-datapackage`, we only support the

docs/design/index.qmd

@@ -42,7 +42,7 @@ Overall, `check-datapackage` must:
 -   Provide clear, user-friendly, and structured messages about any
     issues, identifying where in the descriptor the issues occur.
 -   Provide a strict mode that enforces all aspects of the Data Package
-    standard, including all recommendations.
+    standard, including "SHOULD" checks of properties that should be included or should be in a specific format.
 -   Be designed in a way that can be extended as a command-line
     interface (CLI) in the future.
 

docs/guide/config.qmd

@@ -13,8 +13,17 @@ are available:
 -   `exclusions`: A list of checks to exclude.
 -   `custom_checks`: The list of custom checks to run in addition to the
     checks defined in the standard.
--   `strict`: Whether to run recommended checks in addition to required
-    ones. Defaults to `False`.
+-   `strict`: Whether to include "SHOULD" checks in addition to "MUST"
+    checks. Defaults to `False`.
+
+::: callout-important
+The Data Package standard uses language from [RFC
+2119](https://www.ietf.org/rfc/rfc2119.txt) to define its specifications.
+They use "MUST" for required properties and "SHOULD" for properties that
+should be included but are not strictly required. We try to match this
+language in `check-datapackage` by using the terms "MUST" and "SHOULD",
+though we also use "required" for "MUST" in our documentation.
+:::
 
 ## Excluding checks
 
@@ -156,11 +165,13 @@ issue flagging the first license attached to the Data Package.
 
 ## Strict mode
 
-The Data Package standard has both requirements and recommendations. By
-default, `check()` only checks requirements. Recommendations can be
-turned on by setting the `strict` argument to `True`. The example below
-violates the recommendation that the package `name` should contain no
-special characters.
+The Data Package standard includes properties that "MUST" and "SHOULD"
+be included and/or have a specific format in a compliant Data Package. By default, `check()` only
+the `check()` function only includes "MUST" checks. To include "SHOULD" checks,
+set the `strict` argument to `True`. For example,
+the `name` field of a Data Package "SHOULD" not contain special
+characters. So running `check()` in strict mode (`strict=True`) on the following
+properties would output an issue.
 
 ```{python}
 #| eval: false

index.qmd

@@ -44,7 +44,7 @@ to ensure that your metadata is compliant with the standard.
 -   Provides clear and user-friendly messages that point directly to
     where issues occur in the metadata.
 -   Supports a strict mode that enforces full compliance with the
-    standard, including all recommendations.
+    standard, including not only the checks defined by the Data Package specification as "MUST" but also those marked as "SHOULD".
 
 :warning: Note that `check-datapackage` only checks the metadata in your
 `datapackage.json` file against the Data Package standard---it does not

src/check_datapackage/config.py

@@ -14,8 +14,9 @@ class Config:
             be excluded (i.e., removed from the output of the check function).
         custom_checks (list[CustomCheck]): Custom checks listed here will be done in
             addition to checks defined in the Data Package standard.
-        strict (bool): Whether to run recommended as well as required checks. If
-            True, recommended checks will also be run. Defaults to False.
+        strict (bool): Whether to include "SHOULD" checks in addition to "MUST" checks
+            from the Data Package standard. If True, "SHOULD" checks will also be
+            included. Defaults to False.
         version (str): The version of the Data Package standard to check against.
             Defaults to "v2".
 

tests/test_check.py

@@ -9,7 +9,7 @@
 from check_datapackage.exclusion import Exclusion
 from tests.test_custom_check import lowercase_check
 
-# Without recommendations
+# "MUST" checks
 
 
 def test_passes_matching_properties_with_resources():
@@ -86,11 +86,11 @@ def test_fails_properties_with_pattern_mismatch():
     assert issues[0].jsonpath == "$.contributors[0].path"
 
 
-# With recommendations
+# "SHOULD" checks
 
 
-def test_passes_matching_properties_with_recommendations():
-    """Should pass properties matching recommendations."""
+def test_passes_matching_properties_with_should():
+    """Should pass properties matching "SHOULD" specifications."""
     properties = {
         "name": "a-name-with-no-spaces",
         "title": "A Title",
@@ -106,8 +106,8 @@ def test_passes_matching_properties_with_recommendations():
     assert check(properties, config=Config(strict=True)) == []
 
 
-def test_fails_properties_with_missing_required_fields_with_recommendations():
-    """Should fail properties with missing required fields."""
+def test_fails_properties_with_missing_required_fields_in_should():
+    """Should fail properties with missing required properties in strict mode."""
     properties = {
         "resources": [{"name": "a-name-with-no-spaces", "path": "data.csv"}],
     }
@@ -118,8 +118,8 @@ def test_fails_properties_with_missing_required_fields_with_recommendations():
     assert all(issue.type == "required" for issue in issues)
 
 
-def test_fails_properties_violating_recommendations():
-    """Should fail properties that do not meet the recommendations."""
+def test_fails_properties_violating_should():
+    """Should fail properties that do not meet "SHOULD" specifications."""
     properties = {
         "name": "a name with spaces",
         "id": "123",