docs/howto: use encoding/{json,yaml}.Validate{,Partial}

This adds 2 Commented CUE guides demonstrating how to use json.Validate
and yaml.ValidatePartial as field validators to assert that a string
containing JSON or YAML is compatible with a CUE schema; and how to use
yaml.Validate to assert that such a string is an instance of a schema.

Simplistic schemas are used for the examples due to (at least)
json.Validate providing less-than-helpful error output when dealing with
fields that aren't allowed, for which cue-lang/cue#2782 has been opened.

A similar problem occurs when handling multiple validation failures in
the same stringified data (cf. cue-lang/cue#2079), further requiring the
simplified examples included here.

The asymmetry of json.Validate matching yaml.ValidatePartial (with
yaml.Validate sitting alone, unmatched in its role by any function in
the json package) seems odd. cue-lang/cue#2800 has been opened.

Preview-Path: /docs/howto/use-encoding-json-validate-as-a-field-validator/
Preview-Path: /docs/howto/use-encoding-yaml-validate-encoding-yaml-validatepartial-as-field-validators/
Change-Id: I1259882312308c83ab3fa24538f96cd072ebc310
Signed-off-by: Jonathan Matthews <[email protected]>
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cuelang.org/+/1176034
Reviewed-by: Paul Jolly <[email protected]>
TryBot-Result: CUEcueckoo <[email protected]>

content/docs/howto/use-encoding-json-validate-as-a-field-validator/en.md

@@ -0,0 +1,72 @@
+---
+title: Using "encoding/json.Validate" as a field validator
+tags:
+- commented cue
+- encodings
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in function
+[`encoding/json.Validate`](https://pkg.go.dev/cuelang.org/go/pkg/encoding/json#Validate)
+as a field validator.
+
+It asserts that properly-formed JSON, encoded in a string, adheres to specific
+constraints by checking that the data and schema unify successfully.
+
+{{{with code "en" "cc"}}}
+#location top bottom
+
+! exec cue vet
+cmp stderr out
+-- file.cue --
+package example
+
+import "encoding/json"
+
+data: """
+	{
+	  "a": 1,
+	  "b": "two"
+	}
+	"""
+
+// Validate requires only that data adheres to schema constraints.
+// Missing fields do not cause validation failures.
+data: json.Validate(_outOfBoundsSchema)
+data: json.Validate(_missingFieldSchema)
+
+_outOfBoundsSchema: {
+	a!: >99 // validation failure
+	b!: string
+}
+_missingFieldSchema: {
+	a!: int
+	b!: string
+	c!: bool // NOT a validation failure
+}
+-- out --
+data: invalid value "{\n  \"a\": 1,\n  \"b\": \"two\"\n}" (does not satisfy encoding/json.Validate({a!:>99,b!:string})): error in call to encoding/json.Validate: invalid value 1 (out of bound >99):
+    ./file.cue:14:7
+    ./file.cue:5:7
+    ./file.cue:15:7
+    ./file.cue:18:6
+    json.Validate:2:8
+{{{end}}}
+
+{{< info >}}
+`encoding/json.Validate` validates JSON data *that is encoded in a string*.
+
+To validate data stored in a separate `.json` file, use CUE's native and
+simpler unification instead.\
+This is documented in
+[validating JSON with CUE]({{< relref "../validate-json-using-cue" >}})
+{{< /info >}}
+
+## Related content
+
+- {{< linkto/related/howto "use-encoding-yaml-validate-encoding-yaml-validatepartial-as-field-validators" >}}
+- The [`encoding/json`](https://pkg.go.dev/cuelang.org/go/pkg/encoding/json)
+  built-in package

content/docs/howto/use-encoding-json-validate-as-a-field-validator/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-encoding-json-validate-as-a-field-validator": {
+					page: {
+						cache: {
+							code: {
+								cc: "Ctg5Ic9BX+2N0Bj+tUWQUofQm2WU/uTsWKd+5DmLJI8="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/use-encoding-json-validate-as-a-field-validator/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-encoding-json-validate-as-a-field-validator": {}

content/docs/howto/use-encoding-yaml-validate-encoding-yaml-validatepartial-as-field-validators/en.md

@@ -0,0 +1,95 @@
+---
+title: Using "encoding/yaml.Validate" and "encoding/yaml.ValidatePartial" as field validators
+tags:
+- commented cue
+- encodings
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in functions
+[`encoding/yaml.Validate`](https://pkg.go.dev/cuelang.org/go/pkg/encoding/yaml#Validate)
+and
+[`encoding/yaml.ValidatePartial`](https://pkg.go.dev/cuelang.org/go/pkg/encoding/yaml#ValidatePartial)
+as field validators.
+
+They assert that properly-formed YAML, encoded in a string, adheres to specific
+constraints by checking that the data and schema unify successfully.
+`encoding.yaml/Validate` also requires that all non-optional fields are
+present.
+
+{{{with code "en" "cc"}}}
+#location top bottom
+
+! exec cue vet
+cmp stderr out
+-- file.cue --
+package example
+
+import "encoding/yaml"
+
+data: """
+	a: 1
+	b: "two"
+	"""
+
+// Validate requires that all non-optional fields in a schema are present in
+// data, and that data adheres to schema constraints.
+data: yaml.Validate(_outOfBoundsSchema)
+data: yaml.Validate(_missingFieldSchema)
+
+// ValidatePartial requires only that data adheres to schema constraints.
+data: yaml.ValidatePartial(_outOfBoundsSchema)
+data: yaml.ValidatePartial(_missingFieldSchema)
+
+_outOfBoundsSchema: {
+	a!: >99 // validation failure for both functions
+	b!: string
+}
+_missingFieldSchema: {
+	a!: int
+	b!: string
+	c!: bool // validation failure for yaml.Validate only
+}
+-- out --
+data: invalid value "a: 1\nb: \"two\"" (does not satisfy encoding/yaml.Validate({a!:>99,b!:string})): error in call to encoding/yaml.Validate: invalid value 1 (out of bound >99):
+    ./file.cue:12:7
+    ./file.cue:5:7
+    ./file.cue:13:7
+    ./file.cue:16:7
+    ./file.cue:17:7
+    ./file.cue:20:6
+    yaml.Validate:1:4
+data: invalid value "a: 1\nb: \"two\"" (does not satisfy encoding/yaml.Validate({a!:int,b!:string,c!:bool})): error in call to encoding/yaml.Validate: field is required but not present:
+    ./file.cue:13:7
+    ./file.cue:5:7
+    ./file.cue:12:7
+    ./file.cue:16:7
+    ./file.cue:17:7
+    ./file.cue:26:2
+data: invalid value "a: 1\nb: \"two\"" (does not satisfy encoding/yaml.ValidatePartial({a!:>99,b!:string})): error in call to encoding/yaml.ValidatePartial: invalid value 1 (out of bound >99):
+    ./file.cue:16:7
+    ./file.cue:5:7
+    ./file.cue:12:7
+    ./file.cue:13:7
+    ./file.cue:17:7
+    ./file.cue:20:6
+    yaml.ValidatePartial:1:4
+{{{end}}}
+
+{{< info >}}
+These functions validate YAML data *that is encoded in a string*.
+
+To validate data stored in a separate `.yaml` file, use CUE's native and
+simpler unification instead.\
+This is documented in
+[validating YAML with CUE]({{< relref "../validate-yaml-using-cue" >}})
+{{< /info >}}
+
+## Related content
+
+- {{< linkto/related/howto "use-encoding-json-validate-as-a-field-validator" >}}
+- The [`encoding/yaml`](https://pkg.go.dev/cuelang.org/go/pkg/encoding/yaml)
+  built-in package

content/docs/howto/use-encoding-yaml-validate-encoding-yaml-validatepartial-as-field-validators/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-encoding-yaml-validate-encoding-yaml-validatepartial-as-field-validators": {
+					page: {
+						cache: {
+							code: {
+								cc: "NwmV91mXtPzz8yX9M1F7AuxkKXbsTp/ostoF9i0KF+A="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/use-encoding-yaml-validate-encoding-yaml-validatepartial-as-field-validators/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-encoding-yaml-validate-encoding-yaml-validatepartial-as-field-validators": {}

hugo/content/en/docs/howto/use-encoding-json-validate-as-a-field-validator/index.md

@@ -0,0 +1,71 @@
+---
+title: Using "encoding/json.Validate" as a field validator
+tags:
+- commented cue
+- encodings
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in function
+[`encoding/json.Validate`](https://pkg.go.dev/cuelang.org/go/pkg/encoding/json#Validate)
+as a field validator.
+
+It asserts that properly-formed JSON, encoded in a string, adheres to specific
+constraints by checking that the data and schema unify successfully.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top" >}}
+package example
+
+import "encoding/json"
+
+data: """
+	{
+	  "a": 1,
+	  "b": "two"
+	}
+	"""
+
+// Validate requires only that data adheres to schema constraints.
+// Missing fields do not cause validation failures.
+data: json.Validate(_outOfBoundsSchema)
+data: json.Validate(_missingFieldSchema)
+
+_outOfBoundsSchema: {
+	a!: >99 // validation failure
+	b!: string
+}
+_missingFieldSchema: {
+	a!: int
+	b!: string
+	c!: bool // NOT a validation failure
+}
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}}
+$ cue vet
+data: invalid value "{\n  \"a\": 1,\n  \"b\": \"two\"\n}" (does not satisfy encoding/json.Validate({a!:>99,b!:string})): error in call to encoding/json.Validate: invalid value 1 (out of bound >99):
+    ./file.cue:14:7
+    ./file.cue:5:7
+    ./file.cue:15:7
+    ./file.cue:18:6
+    json.Validate:2:8
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+{{< info >}}
+`encoding/json.Validate` validates JSON data *that is encoded in a string*.
+
+To validate data stored in a separate `.json` file, use CUE's native and
+simpler unification instead.\
+This is documented in
+[validating JSON with CUE]({{< relref "../validate-json-using-cue" >}})
+{{< /info >}}
+
+## Related content
+
+- {{< linkto/related/howto "use-encoding-yaml-validate-encoding-yaml-validatepartial-as-field-validators" >}}
+- The [`encoding/json`](https://pkg.go.dev/cuelang.org/go/pkg/encoding/json)
+  built-in package

hugo/content/en/docs/howto/use-encoding-yaml-validate-encoding-yaml-validatepartial-as-field-validators/index.md

@@ -0,0 +1,94 @@
+---
+title: Using "encoding/yaml.Validate" and "encoding/yaml.ValidatePartial" as field validators
+tags:
+- commented cue
+- encodings
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in functions
+[`encoding/yaml.Validate`](https://pkg.go.dev/cuelang.org/go/pkg/encoding/yaml#Validate)
+and
+[`encoding/yaml.ValidatePartial`](https://pkg.go.dev/cuelang.org/go/pkg/encoding/yaml#ValidatePartial)
+as field validators.
+
+They assert that properly-formed YAML, encoded in a string, adheres to specific
+constraints by checking that the data and schema unify successfully.
+`encoding.yaml/Validate` also requires that all non-optional fields are
+present.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top" >}}
+package example
+
+import "encoding/yaml"
+
+data: """
+	a: 1
+	b: "two"
+	"""
+
+// Validate requires that all non-optional fields in a schema are present in
+// data, and that data adheres to schema constraints.
+data: yaml.Validate(_outOfBoundsSchema)
+data: yaml.Validate(_missingFieldSchema)
+
+// ValidatePartial requires only that data adheres to schema constraints.
+data: yaml.ValidatePartial(_outOfBoundsSchema)
+data: yaml.ValidatePartial(_missingFieldSchema)
+
+_outOfBoundsSchema: {
+	a!: >99 // validation failure for both functions
+	b!: string
+}
+_missingFieldSchema: {
+	a!: int
+	b!: string
+	c!: bool // validation failure for yaml.Validate only
+}
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}}
+$ cue vet
+data: invalid value "a: 1\nb: \"two\"" (does not satisfy encoding/yaml.Validate({a!:>99,b!:string})): error in call to encoding/yaml.Validate: invalid value 1 (out of bound >99):
+    ./file.cue:12:7
+    ./file.cue:5:7
+    ./file.cue:13:7
+    ./file.cue:16:7
+    ./file.cue:17:7
+    ./file.cue:20:6
+    yaml.Validate:1:4
+data: invalid value "a: 1\nb: \"two\"" (does not satisfy encoding/yaml.Validate({a!:int,b!:string,c!:bool})): error in call to encoding/yaml.Validate: field is required but not present:
+    ./file.cue:13:7
+    ./file.cue:5:7
+    ./file.cue:12:7
+    ./file.cue:16:7
+    ./file.cue:17:7
+    ./file.cue:26:2
+data: invalid value "a: 1\nb: \"two\"" (does not satisfy encoding/yaml.ValidatePartial({a!:>99,b!:string})): error in call to encoding/yaml.ValidatePartial: invalid value 1 (out of bound >99):
+    ./file.cue:16:7
+    ./file.cue:5:7
+    ./file.cue:12:7
+    ./file.cue:13:7
+    ./file.cue:17:7
+    ./file.cue:20:6
+    yaml.ValidatePartial:1:4
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+{{< info >}}
+These functions validate YAML data *that is encoded in a string*.
+
+To validate data stored in a separate `.yaml` file, use CUE's native and
+simpler unification instead.\
+This is documented in
+[validating YAML with CUE]({{< relref "../validate-yaml-using-cue" >}})
+{{< /info >}}
+
+## Related content
+
+- {{< linkto/related/howto "use-encoding-json-validate-as-a-field-validator" >}}
+- The [`encoding/yaml`](https://pkg.go.dev/cuelang.org/go/pkg/encoding/yaml)
+  built-in package