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
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cuelang.org/+/1176893
TryBot-Result: CUEcueckoo <[email protected]>
Reviewed-by: Paul Jolly <[email protected]>

content/docs/howto/disallow-a-specific-field-name/en.md

@@ -0,0 +1,63 @@
+---
+title: Disallowing specific field names
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to disallow specific data fields inside an otherwise open
+schema.
+
+{{{with code "en" "emit"}}}
+! exec cue vet . 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}}}
+
+Another common way to prevent the existence of unwanted 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. However, in situations such as the example above, closedness
+cannot be used to disallow specific fields because the schema author cannot
+specify each and every acceptable field - and therefore the schema must be left
+open.
+
+{{< info >}}
+The technique demonstrated here may be superseded by the `error()` builtin
+function proposed in {{< issue 943 />}}.
+
+**This function 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"
+  >}})
+- {{< issue 943 >}}Issue #943{{< /issue >}} contains details of the proposed
+  `error()` builtin function

content/docs/howto/disallow-a-specific-field-name/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"disallow-a-specific-field-name": {
+					page: {
+						cache: {
+							code: {
+								emit: "0HzHGQSXaEWhP1dMM1Xv0g1OovJhrQQko7RHdVMYxCg="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/disallow-a-specific-field-name/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "disallow-a-specific-field-name": {}

hugo/content/en/docs/howto/disallow-a-specific-field-name/index.md

@@ -0,0 +1,65 @@
+---
+title: Disallowing specific field names
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to disallow specific data fields inside an otherwise open
+schema.
+
+{{< 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 . data.yaml
+explicit error (_|_ literal) in source:
+    ./file.cue:10:7
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+Another common way to prevent the existence of unwanted 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. However, in situations such as the example above, closedness
+cannot be used to disallow specific fields because the schema author cannot
+specify each and every acceptable field - and therefore the schema must be left
+open.
+
+{{< info >}}
+The technique demonstrated here may be superseded by the `error()` builtin
+function proposed in {{< issue 943 />}}.
+
+**This function 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"
+  >}})
+- {{< issue 943 >}}Issue #943{{< /issue >}} contains details of the proposed
+  `error()` builtin function