Skip to content

Commit 0d93390

Browse files
lwjohnst86signekbpre-commit-ci[bot]joelostblom
authored
docs: 📝 explain why we call it "check", not "validate" (#196)
# Description I wanted to explain why we don't use validate, for any readers who are interested. Closes #181 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> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Joel Ostblom <joelostblom@users.noreply.github.com>
1 parent 3dfd64e commit 0d93390

File tree

1 file changed

+30
-6
lines changed

1 file changed

+30
-6
lines changed

docs/design/architecture.qmd

Lines changed: 30 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,6 @@ things consistent. However, we also introduce some new terms and
3939
concepts specific to `check-datapackage`. The main objects and actions
4040
used throughout the package can be found in the tables below.
4141

42-
### Objects
43-
4442
| Object | Description |
4543
|----------------------------|--------------------------------------------|
4644
| package | A Data Package that contains a collection of related data resources and descriptor(s). |
@@ -51,8 +49,6 @@ used throughout the package can be found in the tables below.
5149

5250
: Objects used throughout `check-datapackage`.
5351

54-
### Actions
55-
5652
| Action | Description |
5753
|----------------------------|--------------------------------------------|
5854
| check | Check that properties comply with the Data Package standard. |
@@ -61,6 +57,34 @@ used throughout the package can be found in the tables below.
6157

6258
: Actions that `check-datapackage` can perform.
6359

60+
### "Why "check" (and not "validate" or "verify")?
61+
62+
If you have ever searched for tools that check something against a
63+
specification, you'll often see the word "validate". You might also
64+
notice that we don't use the word "validate" in our package and
65+
documentation. This is intentional.
66+
67+
Although the word "validate" is ubiquitous in programming, it's often
68+
used loosely and in ways that don't align from its actual meaning. Tools
69+
that "validate" something often, in practice, *verify* that something
70+
matches a defined expectation or specification.
71+
There are many websites and articles comparing the difference
72+
between validate and verify. For a good overview, see the Wikipedia on
73+
this topic in
74+
[general](https://en.wikipedia.org/wiki/Verification_and_validation) and
75+
on
76+
[software](https://en.wikipedia.org/wiki/Software_verification_and_validation)
77+
specifically.
78+
79+
Unfortunately, "verify" and "validate" are often used interchangeably
80+
and because of that it can be difficult to distinguish between their
81+
meanings. This may be due to the similarity in their spelling and
82+
pronunciation. For that reason, we've decided to use neither of those
83+
words. Instead, we wanted to use a more common word that reflects what
84+
we want this package to do while also being generic enough to encompass
85+
different uses. So we went with "check", since this package *checks*
86+
that the metadata is correct (based on the specification).
87+
6488
## C4 Models
6589

6690
This section contains the [C4 Models](https://c4model.com/) for
@@ -78,8 +102,8 @@ Data Package standard.
78102
`check-datapackage` receives the definitions of the Data Package
79103
descriptor's structure---including properties that [must or
80104
should](https://datapackage.org/standard/data-package/#language) be
81-
included and their formats---from the Data Package standard (version 2). The
82-
standard provides this information through versioned JSON Schema
105+
included and their formats---from the Data Package standard (version 2).
106+
The standard provides this information through versioned JSON Schema
83107
profiles that define required properties and textual descriptions that
84108
outline compliance.
85109

0 commit comments

Comments
 (0)