Skip to content

Explain the behavior of if versus empty #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions docs/syntax.md
Original file line number Diff line number Diff line change
Expand Up @@ -359,6 +359,7 @@ Makes specifications conditional. This means that they are only verified if anot

```yaml
lifestage:
empty: True
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remark that we need this empty: True, as there is an implicit empty: False for all terms and within the if condition, empty values are actually possible.

if:
- sex:
allowed: [male, female] # If sex is "male" or "female"...
Expand Down Expand Up @@ -413,3 +414,58 @@ province:
allowed: 'West Flanders' # Only then it is tested if province is
# "West Flanders".
```

Note: The usage of an `if` valdiation will further differentiate a general `empty: True` statement for that specific field. For example, according to the following whip specification, the field `lifestage` can not be empty when the field `sex` is equal to `male` (the only valid option is `adult`):

```yaml
sex:
empty: True
lifestage:
empty: True
if:
sex:
allowed: [male]
allowed: [adult]
```

For all other values (not affected by the condition of the `sex` field), the value can be empty. In case one needs to provide the possibility of empty values when `sex` is equal to `male` as well, add the `empty: True` statement inside the `if`:

```yaml
sex:
empty: True
lifestage:
empty: True
if:
sex:
allowed: [male]
allowed: [adult]
empty: True
```

The `empty` rule always gets priority over all other specifications and each term without an `empty` specification gets virtually an `empty: False` statement (remember, empty values are not allowed by default).

Check the first example:

```yaml
lifestage:
empty: True
if:
- sex:
allowed: [male, female] # If sex is "male" or "female"...
allowed: adult # ... then lifestage needs to be "adult".
- sex:
allowed: '' # If sex is empty (and nothing else)...
empty: True
allowed: '' # ... then lifestage needs to be empty.
empty: True
```

We can read the specification as follows:

>The value of `lifestage` can be empty (general `empty: True` specification). Next, the `if` statement differentiates the possibility of empty values:
>
>1. When `sex` is equal to `male` or `female`, lifestage can not be empty, but needs to be `adult` (and nothing else)
>2. When `sex` is empty, `lifestage` need to be empty as well (and nothing else)