1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

diff --git a/README.md b/README.md
index 83527108b379da08fceed5d4e12cdf95cec65e6b..10e0111bd080156d9f229e55c7941c69379568db 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # cuesonnet
 
-CUE + Jsonnet
+Validate [Jsonnet](https://jsonnet.org/) data against [CUE](https://cuelang.org/) constraints.
 
 ## Usage
 
@@ -53,6 +53,12 @@ if err := schema.Decode(r, &result); err != nil {
     // handle validation errors
 }
 ```
+
+## Schema notes
+
+**Human-readable errors:** CUE constraint errors surface raw expressions by default (e.g. `out of bound =~"..."`). Use `| error("message")` in your schema to replace them with plain language - see `#Title` in the example above.
+
+**`float` vs `number`:** JSON has one number type. go-jsonnet serializes `50.0` as `50`, which CUE treats as `int` and rejects against `float`. Use `number` for fields that should accept whole-number values; reserve `float` only when integers must be rejected.
 
 ## Tests
 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

diff --git a/cuesonnet.go b/cuesonnet.go
index 38292f174ebe31fcfcff346a6bff93248750812a..89ac1cdbfa49727f55905d22b627ab0d670291f7 100644
--- a/cuesonnet.go
+++ b/cuesonnet.go
@@ -49,7 +49,11 @@ 		var errs []string
 		for _, e := range errors.Errors(err) {
 			errs = append(errs, strings.TrimPrefix(e.Error(), "data."))
 		}
-		return fmt.Errorf("config failed validation with %d errors:\n%s", len(errs), strings.Join(errs, "\n"))
+		noun := "error"
+		if len(errs) > 1 {
+			noun += "s"
+		}
+		return fmt.Errorf("validation failed with %d %s:\n%s", len(errs), noun, strings.Join(errs, "\n"))
 	}
 
 	if err := unified.Decode(&v); err != nil {