encoding/jsonschema: support single schema not at root

Currently it's possible to ask encoding/jsonschema to
decode a set of named schemas not at the root
of the data document passed in by using `Config.Root`.

However, it's not possible to ask for a single schema not
at the root. Since that schema might refer to
other schemas within the same JSON data,
it's not quite as simple as extracting the sub-schema
and then passing it to encoding/jsonschema.

Support this mode by adding `Config.SingleRoot` to
enable it.

This will help us to translate Kubernetes CRD files.

Also in passing make `jsonschema.Config.Root` work with
integer indexes, as the schema in CRD files is inside an
array. There's still an ambiguity but it seems much less likely
that there will be named roots inside integerlike string fields
than inside arrays.

For #2691

Signed-off-by: Roger Peppe <[email protected]>
Change-Id: I0870632d7261f37a460a161b722af64539534314
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/1209501
TryBot-Result: CUEcueckoo <[email protected]>
Unity-Result: CUE porcuepine <[email protected]>
Reviewed-by: Daniel Martí <[email protected]>

Author: rogpeppe

encoding/jsonschema/decode.go

@@ -122,19 +122,33 @@ func (d *decoder) addImport(n cue.Value, pkg string) *ast.Ident {
 
 func (d *decoder) decode(v cue.Value) *ast.File {
 	var defsRoot cue.Value
+	// docRoot represents the root of the actual data, by contrast
+	// with the "root" value as specified in [Config.Root] which
+	// represents the root of the schemas to be decoded.
+	docRoot := v
 	if d.cfg.Root != "" {
-		defsPath, err := parseRootRef(d.cfg.Root)
+		rootPath, err := parseRootRef(d.cfg.Root)
 		if err != nil {
 			d.errf(cue.Value{}, "invalid Config.Root value %q: %v", d.cfg.Root, err)
 			return nil
 		}
-		defsRoot = v.LookupPath(defsPath)
-		if !defsRoot.Exists() && d.cfg.AllowNonExistentRoot {
-			defsRoot = v.Context().CompileString("{}")
-		} else if defsRoot.Kind() != cue.StructKind {
-			d.errf(defsRoot, "value at path %v must be struct containing definitions but is actually %v", d.cfg.Root, defsRoot)
+		root := v.LookupPath(rootPath)
+		if !root.Exists() && !d.cfg.AllowNonExistentRoot {
+			d.errf(v, "root value at path %v does not exist", d.cfg.Root)
 			return nil
 		}
+		if d.cfg.SingleRoot {
+			v = root
+		} else {
+			if !root.Exists() {
+				root = v.Context().CompileString("{}")
+			}
+			if root.Kind() != cue.StructKind {
+				d.errf(root, "value at path %v must be struct containing definitions but is actually %v", d.cfg.Root, root)
+				return nil
+			}
+			defsRoot = root
+		}
 	}
 
 	var rootInfo schemaInfo
@@ -160,7 +174,7 @@ func (d *decoder) decode(v cue.Value) *ast.File {
 				id:            d.rootID,
 			},
 			isRoot: true,
-			pos:    v,
+			pos:    docRoot,
 		}
 
 		if defsRoot.Exists() {

encoding/jsonschema/decode_test.go

@@ -98,10 +98,14 @@ func TestDecode(t *testing.T) {
 				cfg.DefaultVersion = vers
 			}
 		}
+		if root, ok := t.Value("root"); ok {
+			cfg.Root = root
+		}
 		cfg.Strict = t.HasTag("strict")
 		cfg.StrictKeywords = cfg.StrictKeywords || t.HasTag("strictKeywords")
 		cfg.AllowNonExistentRoot = t.HasTag("allowNonExistentRoot")
 		cfg.StrictFeatures = t.HasTag("strictFeatures")
+		cfg.SingleRoot = t.HasTag("singleRoot")
 		cfg.PkgName, _ = t.Value("pkgName")
 
 		ctx := t.CueContext()

encoding/jsonschema/jsonschema.go

@@ -113,7 +113,7 @@ type Config struct {
 	// JSON reference of location containing schemas. The empty string indicates
 	// that there is a single schema at the root. If this is non-empty,
 	// the referred-to location should be an object, and each member
-	// is taken to be a schema.
+	// is taken to be a schema (by default: see [Config.SingleRoot])
 	//
 	// Examples:
 	//  "#/" or "#"                    top-level fields are schemas.
@@ -124,6 +124,11 @@ type Config struct {
 	// only. Just `#` is preferred.
 	Root string
 
+	// SingleRoot is consulted only when Root is non-empty.
+	// If Root is non-empty and SingleRoot is true, then
+	// Root should specify the location of a single schema to extract.
+	SingleRoot bool
+
 	// AllowNonExistentRoot prevents an error when there is no value at
 	// the above Root path. Such an error can be useful to signal that
 	// the data may not be a JSON Schema, but is not always a good idea.

encoding/jsonschema/ref.go

@@ -48,10 +48,14 @@ func parseRootRef(str string) (cue.Path, error) {
 	fragmentParts := slices.Collect(jsonPointerTokens(u.Fragment))
 	var selectors []cue.Selector
 	for _, r := range fragmentParts {
-		// Technically this is incorrect because a numeric
-		// element could also index into a list, but the
-		// resulting CUE path will not allow that.
-		selectors = append(selectors, cue.Str(r))
+		if i, err := strconv.ParseUint(r, 10, 64); err == nil && strconv.FormatUint(i, 10) == r {
+			// Technically this is incorrect because a numeric element
+			// could also be a string selector and the resulting path
+			// will not allow that.
+			selectors = append(selectors, cue.Index(int64(i)))
+		} else {
+			selectors = append(selectors, cue.Str(r))
+		}
 	}
 	return cue.MakePath(selectors...), nil
 }

encoding/jsonschema/testdata/txtar/openapi_nonexistent_error.txtar

@@ -6,4 +6,4 @@ Test what happens when there's an OpenAPI schema that has no
 -- schema.yaml --
 -- out/decode/extract --
 ERROR:
-value at path #/components/schemas/ must be struct containing definitions but is actually _|_ // field not found: components
+root value at path #/components/schemas/ does not exist

encoding/jsonschema/testdata/txtar/singleschema_notroot.txtar

@@ -0,0 +1,35 @@
+#root: #/spec/versions/0/schema/openAPIV3Schema
+#singleRoot
+
+-- schema.yaml --
+---
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+spec:
+  group: example.io
+  scope: Namespaced
+  versions:
+    - name: v2
+      schema:
+        openAPIV3Schema:
+          description: Something about a CRD.
+          type: object
+          properties:
+            foo:
+              description: description of foo
+              type: string
+            bar:
+              description: description of bar
+              allOf:
+                - $ref: '#/spec/versions/0/schema/openAPIV3Schema/properties/foo'
+-- out/decode/extract --
+// Something about a CRD.
+// description of foo
+foo?: _#defs."/spec/versions/0/schema/openAPIV3Schema/properties/foo"
+
+// description of bar
+bar?: _#defs."/spec/versions/0/schema/openAPIV3Schema/properties/foo"
+
+// description of foo
+_#defs: "/spec/versions/0/schema/openAPIV3Schema/properties/foo": string
+...