Switched to API field name as primary metadata (#14711)

Author: melinath

docs/content/reference/metadata.md

@@ -39,7 +39,7 @@ The API URL patterns used by this resource that represent variants e.g., "folder
 
 The list of fields used by this resource. Each field can contain the following attributes:
 
-- `field`: The name of the field in Terraform, including the path e.g., "build_config.source.storage_source.bucket"
-- `api_field`: The name of the field in the API, including the path e.g., "build_config.source.storage_source.bucket". Defaults to the value of `field`.
-- `provider_only`: If true, the field is only present in the provider. This primarily applies for virtual fields and url-only parameters. When set to true, `api_field` should be left empty, as it will be ignored. Default: `false`.
+- `api_field`: The name of the field in the REST API, including the path e.g., "buildConfig.source.storageSource.bucket".
+- `field`: The name of the field in Terraform, including the path e.g., "build_config.source.storage_source.bucket". Defaults to the value of `api_field` converted to snake_case.
+- `provider_only`: If true, the field is only present in the provider. This primarily applies for virtual fields and url-only parameters. When set to true, `field` should be set and `api_field` should be left empty. Default: `false`.
 - `json`: If true, this is a JSON field which "covers" all child API fields. As a special case, JSON fields which cover an entire resource can have `api_field` set to `*`.

mmv1/api/type.go

@@ -467,20 +467,37 @@ func (t Type) MetadataLineage() string {
 	return fmt.Sprintf("%s.%s", t.ParentMetadata.MetadataLineage(), google.Underscore(t.Name))
 }
 
+// Returns a dot notation path to where the field is nested within the parent
+// object. eg: parent.meta.label.foo
+// This format converts the API field names directly to snake_case, which can be compared against the MetadataLineage
+// to determine whether to include an explicit Terraform field name.
+func (t Type) MetadataDefaultLineage() string {
+	apiName := t.ApiName
+	if t.ParentMetadata == nil {
+		return google.Underscore(apiName)
+	}
+
+	if t.ParentMetadata.IsA("Array") {
+		return t.ParentMetadata.MetadataDefaultLineage()
+	}
+
+	return fmt.Sprintf("%s.%s", t.ParentMetadata.MetadataDefaultLineage(), google.Underscore(apiName))
+}
+
 // Returns a dot notation path to where the field is nested within the parent
 // object. eg: parent.meta.label.foo
 // This format is intended for to represent an API type.
 func (t Type) MetadataApiLineage() string {
 	apiName := t.ApiName
 	if t.ParentMetadata == nil {
-		return google.Underscore(apiName)
+		return apiName
 	}
 
 	if t.ParentMetadata.IsA("Array") {
 		return t.ParentMetadata.MetadataApiLineage()
 	}
 
-	return fmt.Sprintf("%s.%s", t.ParentMetadata.MetadataApiLineage(), google.Underscore(apiName))
+	return fmt.Sprintf("%s.%s", t.ParentMetadata.MetadataApiLineage(), apiName)
 }
 
 // Returns the lineage in snake case

mmv1/api/type_test.go

@@ -256,7 +256,7 @@ func TestMetadataLineage(t *testing.T) {
 	}
 }
 
-func TestMetadataApiLineage(t *testing.T) {
+func TestMetadataDefaultLineage(t *testing.T) {
 	t.Parallel()
 
 	root := Type{
@@ -323,6 +323,87 @@ func TestMetadataApiLineage(t *testing.T) {
 		},
 	}
 
+	for _, tc := range cases {
+		tc := tc
+
+		t.Run(tc.description, func(t *testing.T) {
+			t.Parallel()
+
+			got := tc.obj.MetadataDefaultLineage()
+			if got != tc.expected {
+				t.Errorf("expected %q to be %q", got, tc.expected)
+			}
+		})
+	}
+}
+
+func TestMetadataApiLineage(t *testing.T) {
+	t.Parallel()
+
+	root := Type{
+		Name: "root",
+		Type: "NestedObject",
+		Properties: []*Type{
+			{
+				Name: "foo",
+				Type: "NestedObject",
+				Properties: []*Type{
+					{
+						Name: "bars",
+						Type: "Array",
+						ItemType: &Type{
+							Type: "NestedObject",
+							Properties: []*Type{
+								{
+									Name: "fooBar",
+									Type: "String",
+								},
+							},
+						},
+					},
+				},
+			},
+			{
+				Name:    "baz",
+				ApiName: "bazbaz",
+				Type:    "String",
+			},
+		},
+	}
+	root.SetDefault(&Resource{})
+
+	cases := []struct {
+		description string
+		obj         Type
+		expected    string
+	}{
+		{
+			description: "root type",
+			obj:         root,
+			expected:    "root",
+		},
+		{
+			description: "sub type",
+			obj:         *root.Properties[0],
+			expected:    "root.foo",
+		},
+		{
+			description: "array",
+			obj:         *root.Properties[0].Properties[0],
+			expected:    "root.foo.bars",
+		},
+		{
+			description: "array of objects",
+			obj:         *root.Properties[0].Properties[0].ItemType.Properties[0],
+			expected:    "root.foo.bars.fooBar",
+		},
+		{
+			description: "with api name",
+			obj:         *root.Properties[1],
+			expected:    "root.bazbaz",
+		},
+	}
+
 	for _, tc := range cases {
 		tc := tc
 

mmv1/templates/terraform/metadata.yaml.tmpl

@@ -15,14 +15,16 @@ autogen_status: true
 {{- end }}
 fields:
 {{- range $p := $.LeafProperties }}
+  {{- if $p.ProviderOnly }}
   - field: '{{ $p.MetadataLineage }}'
-    {{- if and (ne $p.MetadataLineage $p.MetadataApiLineage) (not $p.ProviderOnly) }}
-    api_field: '{{ $p.MetadataApiLineage }}'
-    {{- end }}
+    provider_only: true
+  {{- else}}
+  - api_field: '{{ $p.MetadataApiLineage }}'
+    {{- if ne $p.MetadataLineage $p.MetadataDefaultLineage }}
+    field: '{{ $p.MetadataLineage }}'
+    {{- end}}
     {{- if $p.IsJsonField }}
     json: true
     {{- end }}
-    {{- if $p.ProviderOnly }}
-    provider_only: true
-    {{- end }}
+  {{- end}}
 {{- end }}