Skip to content

Commit

Permalink
docs/howto: disallow a specific field name
Browse files Browse the repository at this point in the history
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
jpluscplusm authored and cueckoo committed Feb 14, 2024
1 parent eb2ecd6 commit 6d01341
Show file tree
Hide file tree
Showing 4 changed files with 141 additions and 0 deletions.
59 changes: 59 additions & 0 deletions content/docs/howto/disallow-a-specific-field-name/en.md
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 content/docs/howto/disallow-a-specific-field-name/gen_cache.cue
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="
}
}
}
}
}
}
}
}
3 changes: 3 additions & 0 deletions content/docs/howto/disallow-a-specific-field-name/page.cue
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 hugo/content/en/docs/howto/disallow-a-specific-field-name/index.md
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 />}}

0 comments on commit 6d01341

Please sign in to comment.