-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs/howto: disallow a specific field name
This adds a Commented CUE guide that demonstrates the use of an optional field constraint with a literal _|_ in order to disallow a specific field name from existing. Preview-Path: /docs/howto/disallow-a-specific-field-name/ Signed-off-by: Jonathan Matthews <[email protected]> Change-Id: Id2387e46eb1462a38db268b9f68d2f11e84e5d1f Dispatch-Trailer: {"type":"trybot","CL":1176893,"patchset":2,"ref":"refs/changes/93/1176893/2","targetBranch":"alpha"}
- Loading branch information
1 parent
eb2ecd6
commit 6d01341
Showing
4 changed files
with
141 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,59 @@ | ||
--- | ||
title: Disallowing specific field names | ||
tags: | ||
- commented cue | ||
authors: | ||
- jpluscplusm | ||
toc_hide: true | ||
--- | ||
|
||
A common way to prevent the existence of data fields is to rely on the | ||
**closedness** property that comes from the use of | ||
[**definitions**]({{< relref "docs/tour/basics/definitions" >}}) or the | ||
[**`close`**]({{< relref "docs/reference/glossary#close-built-in-function" >}}) | ||
built-in function. | ||
|
||
In situations where neither of these language features is appropriate then the | ||
technique demonstrated in this | ||
[Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}}) may be used | ||
to prohibit specific data fields from existing. | ||
|
||
{{{with code "en" "emit"}}} | ||
! exec cue vet .:example data.yaml | ||
cmp stderr out | ||
-- file.cue -- | ||
package example | ||
|
||
// This schema is open because we do not know | ||
// which additional fields might be present. | ||
name!: string | ||
address!: string | ||
|
||
// We must not allow our data model to contain | ||
// people's ages, so we disallow the age field. | ||
age?: _|_ | ||
-- data.yaml -- | ||
name: Charlie Cartwright | ||
address: Ripon, North Yorkshire | ||
species: cat | ||
age: 15.5 | ||
-- out -- | ||
explicit error (_|_ literal) in source: | ||
./file.cue:10:7 | ||
{{{end}}} | ||
|
||
{{< info >}} | ||
The technique demonstrated here may be superseded by the `error` validator | ||
described in {{< issue 943 />}}. | ||
|
||
**This validator is not yet available**, but would allow for custom error | ||
messages instead of the\ | ||
`explicit error (_|_ literal) in source` shown above. | ||
{{< /info >}} | ||
|
||
## Related content | ||
|
||
- The CUE Tour: [**Definitions**]({{< relref "docs/tour/basics/definitions" >}}) | ||
- Glossary: | ||
[the **`close`** built-in function]({{< relref "docs/reference/glossary#close-built-in-function" >}}) | ||
- The proposed `error` validator: {{< issue 943 />}} |
18 changes: 18 additions & 0 deletions
18
content/docs/howto/disallow-a-specific-field-name/gen_cache.cue
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,18 @@ | ||
package site | ||
{ | ||
content: { | ||
docs: { | ||
howto: { | ||
"disallow-a-specific-field-name": { | ||
page: { | ||
cache: { | ||
code: { | ||
emit: "UVZNk4H9bbA49jSdLghUQ1oxzM6Zmg2sBYpnzqqLz4s=" | ||
} | ||
} | ||
} | ||
} | ||
} | ||
} | ||
} | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
package site | ||
|
||
content: docs: howto: "disallow-a-specific-field-name": {} |
61 changes: 61 additions & 0 deletions
61
hugo/content/en/docs/howto/disallow-a-specific-field-name/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,61 @@ | ||
--- | ||
title: Disallowing specific field names | ||
tags: | ||
- commented cue | ||
authors: | ||
- jpluscplusm | ||
toc_hide: true | ||
--- | ||
|
||
A common way to prevent the existence of data fields is to rely on the | ||
**closedness** property that comes from the use of | ||
[**definitions**]({{< relref "docs/tour/basics/definitions" >}}) or the | ||
[**`close`**]({{< relref "docs/reference/glossary#close-built-in-function" >}}) | ||
built-in function. | ||
|
||
In situations where neither of these language features is appropriate then the | ||
technique demonstrated in this | ||
[Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}}) may be used | ||
to prohibit specific data fields from existing. | ||
|
||
{{< code-tabs >}} | ||
{{< code-tab name="file.cue" language="cue" area="top-left" >}} | ||
package example | ||
|
||
// This schema is open because we do not know | ||
// which additional fields might be present. | ||
name!: string | ||
address!: string | ||
|
||
// We must not allow our data model to contain | ||
// people's ages, so we disallow the age field. | ||
age?: _|_ | ||
{{< /code-tab >}} | ||
{{< code-tab name="data.yaml" language="yaml" area="top-right" >}} | ||
name: Charlie Cartwright | ||
address: Ripon, North Yorkshire | ||
species: cat | ||
age: 15.5 | ||
{{< /code-tab >}} | ||
{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}} | ||
$ cue vet .:example data.yaml | ||
explicit error (_|_ literal) in source: | ||
./file.cue:10:7 | ||
{{< /code-tab >}} | ||
{{< /code-tabs >}} | ||
|
||
{{< info >}} | ||
The technique demonstrated here may be superseded by the `error` validator | ||
described in {{< issue 943 />}}. | ||
|
||
**This validator is not yet available**, but would allow for custom error | ||
messages instead of the\ | ||
`explicit error (_|_ literal) in source` shown above. | ||
{{< /info >}} | ||
|
||
## Related content | ||
|
||
- The CUE Tour: [**Definitions**]({{< relref "docs/tour/basics/definitions" >}}) | ||
- Glossary: | ||
[the **`close`** built-in function]({{< relref "docs/reference/glossary#close-built-in-function" >}}) | ||
- The proposed `error` validator: {{< issue 943 />}} |