@@ -39,8 +39,6 @@ things consistent. However, we also introduce some new terms and
3939concepts specific to ` check-datapackage ` . The main objects and actions
4040used 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
6690This 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
79103descriptor's structure---including properties that [ must or
80104should] ( 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
83107profiles that define required properties and textual descriptions that
84108outline compliance.
85109
0 commit comments