add tracking required fields

Author: s-urbaniak

tools/scaffolder/internal/generate/indexers.go

@@ -39,6 +39,11 @@ type ReferenceField struct {
 	ReferencedKind    string
 	ReferencedGroup   string
 	ReferencedVersion string
+	// RequiredSegments tracks whether each meaningful path segment is required.
+	// The slice aligns with the meaningful parts of FieldPath (excluding "properties", "items").
+	// For example, for FieldPath "properties.spec.properties.groupRef",
+	// RequiredSegments[0] indicates if "spec" is required, RequiredSegments[1] if "groupRef" is required.
+	RequiredSegments []bool
 }
 
 type IndexerInfo struct {
@@ -179,12 +184,13 @@ func parseAPIMapping(apiMappingsStr string, schema *apiextensionsv1.JSONSchemaPr
 	var references []ReferenceField
 
 	// Recursively search for x-kubernetes-mapping
-	findReferences(mapping, "", schema, &references)
+	// Start with empty requiredSegments slice
+	findReferences(mapping, "", schema, nil, &references)
 
 	return references, nil
 }
 
-func processKubernetesMapping(v map[string]any, path string, references *[]ReferenceField) {
+func processKubernetesMapping(v map[string]any, path string, requiredSegments []bool, references *[]ReferenceField) {
 	kubeMapping, exists := v["x-kubernetes-mapping"]
 	if !exists {
 		return
@@ -217,22 +223,27 @@ func processKubernetesMapping(v map[string]any, path string, references *[]Refer
 	}
 
 	if kind != "" && fieldName != "" {
+		// Make a copy of requiredSegments to avoid sharing the underlying array
+		reqCopy := make([]bool, len(requiredSegments))
+		copy(reqCopy, requiredSegments)
+
 		ref := ReferenceField{
 			FieldName:         fieldName,
 			FieldPath:         path,
 			ReferencedKind:    kind,
 			ReferencedGroup:   group,
 			ReferencedVersion: version,
+			RequiredSegments:  reqCopy,
 		}
 		*references = append(*references, ref)
 	}
 }
 
-func findReferences(data any, path string, schema *apiextensionsv1.JSONSchemaProps, references *[]ReferenceField) {
+func findReferences(data any, path string, schema *apiextensionsv1.JSONSchemaProps, requiredSegments []bool, references *[]ReferenceField) {
 	switch v := data.(type) {
 	case map[string]any:
 		// Check if this is a kubernetes mapping and process it
-		processKubernetesMapping(v, path, references)
+		processKubernetesMapping(v, path, requiredSegments, references)
 
 		for key, value := range v {
 			newPath := path
@@ -243,8 +254,18 @@ func findReferences(data any, path string, schema *apiextensionsv1.JSONSchemaPro
 
 			// Resolve the child schema for this key and pass it into the recursive call
 			required, childSchema := getSchemaForPathSegment(schema, key)
-			_ = required
-			findReferences(value, newPath, childSchema, references)
+
+			// Track required status for meaningful segments (not "properties" or "items")
+			newRequiredSegments := requiredSegments
+			if key != "properties" && key != "items" {
+				// Special case: the top-level "spec" property is never required per Kubernetes convention
+				if key == "spec" && len(requiredSegments) == 0 {
+					required = false
+				}
+				newRequiredSegments = append(requiredSegments, required)
+			}
+
+			findReferences(value, newPath, childSchema, newRequiredSegments, references)
 		}
 	case []any:
 		for i, item := range v {
@@ -253,11 +274,9 @@ func findReferences(data any, path string, schema *apiextensionsv1.JSONSchemaPro
 			// For arrays pass the items schema if available
 			var childSchema *apiextensionsv1.JSONSchemaProps
 			if schema != nil {
-				var required bool
-				required, childSchema = getSchemaForPathSegment(schema, "items")
-				_ = required
+				_, childSchema = getSchemaForPathSegment(schema, "items")
 			}
-			findReferences(item, newPath, childSchema, references)
+			findReferences(item, newPath, childSchema, requiredSegments, references)
 		}
 	}
 }
@@ -285,6 +304,10 @@ func getSchemaForPathSegment(schema *apiextensionsv1.JSONSchemaProps, key string
 	}
 
 	if key == "items" {
+		// Return the items schema for arrays
+		if schema.Items != nil && schema.Items.Schema != nil {
+			return false, schema.Items.Schema
+		}
 		return false, nil
 	}
 

tools/scaffolder/internal/generate/indexers_test.go

@@ -141,6 +141,139 @@ spec:
 	assert.Contains(t, refs[0].FieldPath, ".items.")
 }
 
+func TestParseReferenceFields_RequiredSegments(t *testing.T) {
+	testYAML := `
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: clusters.atlas.generated.mongodb.com
+  annotations:
+    api-mappings: |
+      properties:
+        spec:
+          properties:
+            v20250312:
+              properties:
+                groupRef:
+                  x-kubernetes-mapping:
+                    type:
+                      kind: Group
+                      group: atlas.generated.mongodb.com
+                      version: v1
+spec:
+  group: atlas.generated.mongodb.com
+  names:
+    kind: Cluster
+  versions:
+  - name: v1
+    schema:
+      openAPIV3Schema:
+        type: object
+        required:
+        - spec
+        properties:
+          spec:
+            type: object
+            required:
+            - v20250312
+            properties:
+              v20250312:
+                type: object
+                required:
+                - groupRef
+                properties:
+                  groupRef:
+                    type: object
+                    properties:
+                      name:
+                        type: string
+`
+
+	tmpDir := t.TempDir()
+	testFile := filepath.Join(tmpDir, "test.yaml")
+	err := os.WriteFile(testFile, []byte(testYAML), 0644)
+	require.NoError(t, err)
+
+	refs, err := ParseReferenceFields(testFile, "Cluster")
+	require.NoError(t, err)
+	require.Len(t, refs, 1)
+
+	ref := refs[0]
+	assert.Equal(t, "groupRef", ref.FieldName)
+	assert.Equal(t, "Group", ref.ReferencedKind)
+	assert.Equal(t, "properties.spec.properties.v20250312.properties.groupRef", ref.FieldPath)
+	// spec is never required (Kubernetes convention), v20250312 is required in spec, groupRef is required in v20250312
+	assert.Equal(t, []bool{false, true, true}, ref.RequiredSegments)
+}
+
+func TestParseReferenceFields_MixedRequiredSegments(t *testing.T) {
+	testYAML := `
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: clusters.atlas.generated.mongodb.com
+  annotations:
+    api-mappings: |
+      properties:
+        spec:
+          properties:
+            v20250312:
+              properties:
+                optionalSection:
+                  properties:
+                    groupRef:
+                      x-kubernetes-mapping:
+                        type:
+                          kind: Group
+                          group: atlas.generated.mongodb.com
+                          version: v1
+spec:
+  group: atlas.generated.mongodb.com
+  names:
+    kind: Cluster
+  versions:
+  - name: v1
+    schema:
+      openAPIV3Schema:
+        type: object
+        required:
+        - spec
+        properties:
+          spec:
+            type: object
+            required:
+            - v20250312
+            properties:
+              v20250312:
+                type: object
+                properties:
+                  optionalSection:
+                    type: object
+                    required:
+                    - groupRef
+                    properties:
+                      groupRef:
+                        type: object
+                        properties:
+                          name:
+                            type: string
+`
+
+	tmpDir := t.TempDir()
+	testFile := filepath.Join(tmpDir, "test.yaml")
+	err := os.WriteFile(testFile, []byte(testYAML), 0644)
+	require.NoError(t, err)
+
+	refs, err := ParseReferenceFields(testFile, "Cluster")
+	require.NoError(t, err)
+	require.Len(t, refs, 1)
+
+	ref := refs[0]
+	assert.Equal(t, "groupRef", ref.FieldName)
+	// spec is never required (Kubernetes convention), v20250312 is required, optionalSection is NOT required, groupRef IS required
+	assert.Equal(t, []bool{false, true, false, true}, ref.RequiredSegments)
+}
+
 func TestBuildFieldAccessPath(t *testing.T) {
 	tests := []struct {
 		name      string