Convert OAS property names to valid Terraform identifiers (#59)

* initial implementation

* add docs to design

Author: austinvalle

DESIGN.md

@@ -167,6 +167,19 @@ If the field is only present in a schema other than the `read` operation `parame
 | [pattern](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-pattern)             | [`validators`](https://developer.hashicorp.com/terraform/plugin/code-generation/specification#validators)                            |
 | [uniqueItems](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-uniqueItems)     | [`validators`](https://developer.hashicorp.com/terraform/plugin/code-generation/specification#validators)                            |
 
+### Attribute Names
+After all attributes have been [mapped](#oas-types-to-provider-attributes) and any overrides/aliases have been applied, the attribute names mapped from the OAS will be converted (if needed) to valid [Terraform Identifiers](https://developer.hashicorp.com/terraform/language/syntax/configuration#identifiers). This [logic](https://github.com/hashicorp/terraform-plugin-codegen-openapi/blob/main/internal/mapper/util/framework_identifier.go#L25) performs the following, in order:
+1. Removes all characters that are NOT alphanumeric or an underscore
+2. Removes all leading numbers
+3. Inserts an underscore between any lowercase letter that is immediately followed by an uppercase letter
+4. Lowercases the final result
+
+See the [test cases](https://github.com/hashicorp/terraform-plugin-codegen-openapi/blob/main/internal/mapper/util/framework_identifier_test.go#L15) for examples on the expectations of this conversion process.
+
+This ensures all properties from an OAS are converted to valid Terraform identifiers, but can technically cause conflicts if multiple distinct OAS properties are scrubbed to the same value:
+- `Fake_Thing` -> `fake_thing`
+- `fakeThing` -> `fake_thing`
+
 ## Known Limitations
 As OpenAPI is designed to describe HTTP APIs in general, it doesn't always fully align with [Terraform Provider design principles](https://developer.hashicorp.com/terraform/plugin/best-practices/hashicorp-provider-design-principles). There are pieces of logic in this generator that make assumptions on what portions of the OAS to use when mapping to the provider code specification, however there are some limitations on what can be supported, which are documented below.
 

internal/cmd/testdata/petstore3/generated_framework_ir.json

@@ -18,7 +18,7 @@
 						}
 					},
 					{
-						"name": "petId",
+						"name": "pet_id",
 						"int64": {
 							"computed_optional_required": "computed"
 						}
@@ -30,7 +30,7 @@
 						}
 					},
 					{
-						"name": "shipDate",
+						"name": "ship_date",
 						"string": {
 							"computed_optional_required": "computed",
 							"description": "A field representing the date and time an order will be shipped by"
@@ -87,7 +87,7 @@
 						}
 					},
 					{
-						"name": "photoUrls",
+						"name": "photo_urls",
 						"list": {
 							"computed_optional_required": "computed",
 							"element_type": {
@@ -176,7 +176,7 @@
 						}
 					},
 					{
-						"name": "petId",
+						"name": "pet_id",
 						"int64": {
 							"computed_optional_required": "computed_optional"
 						}
@@ -188,7 +188,7 @@
 						}
 					},
 					{
-						"name": "shipDate",
+						"name": "ship_date",
 						"string": {
 							"computed_optional_required": "computed_optional",
 							"description": "A field representing the date and time an order will be shipped by"
@@ -257,7 +257,7 @@
 						}
 					},
 					{
-						"name": "photoUrls",
+						"name": "photo_urls",
 						"list": {
 							"computed_optional_required": "required",
 							"element_type": {
@@ -320,7 +320,7 @@
 						}
 					},
 					{
-						"name": "firstName",
+						"name": "first_name",
 						"string": {
 							"computed_optional_required": "computed_optional"
 						}
@@ -332,7 +332,7 @@
 						}
 					},
 					{
-						"name": "lastName",
+						"name": "last_name",
 						"string": {
 							"computed_optional_required": "computed_optional"
 						}
@@ -350,7 +350,7 @@
 						}
 					},
 					{
-						"name": "userStatus",
+						"name": "user_status",
 						"int64": {
 							"computed_optional_required": "computed_optional",
 							"description": "User Status"

internal/cmd/testdata/scaleway/generated_framework_ir.json

@@ -311,7 +311,7 @@
 													"computed_optional_required": "computed",
 													"attributes": [
 														{
-															"name": "\u003cextra_volumeKey\u003e",
+															"name": "extra_volume_key",
 															"single_nested": {
 																"computed_optional_required": "computed",
 																"attributes": [
@@ -871,7 +871,7 @@
 										"computed_optional_required": "computed",
 										"attributes": [
 											{
-												"name": "\u003cvolumeKey\u003e",
+												"name": "volume_key",
 												"single_nested": {
 													"computed_optional_required": "computed",
 													"attributes": [
@@ -1403,7 +1403,7 @@
 														"computed_optional_required": "computed",
 														"attributes": [
 															{
-																"name": "\u003cextra_volumeKey\u003e",
+																"name": "extra_volume_key",
 																"single_nested": {
 																	"computed_optional_required": "computed",
 																	"attributes": [
@@ -1963,7 +1963,7 @@
 											"computed_optional_required": "computed",
 											"attributes": [
 												{
-													"name": "\u003cvolumeKey\u003e",
+													"name": "volume_key",
 													"single_nested": {
 														"computed_optional_required": "computed",
 														"attributes": [
@@ -2129,7 +2129,7 @@
 							"computed_optional_required": "computed_optional",
 							"attributes": [
 								{
-									"name": "\u003cextra_volumeKey\u003e",
+									"name": "extra_volume_key",
 									"single_nested": {
 										"computed_optional_required": "computed_optional",
 										"attributes": [
@@ -2366,7 +2366,7 @@
 										"computed_optional_required": "computed",
 										"attributes": [
 											{
-												"name": "\u003cextra_volumeKey\u003e",
+												"name": "extra_volume_key",
 												"single_nested": {
 													"computed_optional_required": "computed",
 													"attributes": [

internal/mapper/attrmapper/bool.go

@@ -5,6 +5,7 @@ package attrmapper
 
 import (
 	"github.com/hashicorp/terraform-plugin-codegen-openapi/internal/explorer"
+	"github.com/hashicorp/terraform-plugin-codegen-openapi/internal/mapper/util"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/datasource"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/provider"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/resource"
@@ -38,7 +39,7 @@ func (a *ResourceBoolAttribute) ApplyOverride(override explorer.Override) (Resou
 
 func (a *ResourceBoolAttribute) ToSpec() resource.Attribute {
 	return resource.Attribute{
-		Name: a.Name,
+		Name: util.TerraformIdentifier(a.Name),
 		Bool: &a.BoolAttribute,
 	}
 }
@@ -71,7 +72,7 @@ func (a *DataSourceBoolAttribute) ApplyOverride(override explorer.Override) (Dat
 
 func (a *DataSourceBoolAttribute) ToSpec() datasource.Attribute {
 	return datasource.Attribute{
-		Name: a.Name,
+		Name: util.TerraformIdentifier(a.Name),
 		Bool: &a.BoolAttribute,
 	}
 }
@@ -84,7 +85,7 @@ type ProviderBoolAttribute struct {
 
 func (a *ProviderBoolAttribute) ToSpec() provider.Attribute {
 	return provider.Attribute{
-		Name: a.Name,
+		Name: util.TerraformIdentifier(a.Name),
 		Bool: &a.BoolAttribute,
 	}
 }

internal/mapper/attrmapper/float64.go

@@ -5,6 +5,7 @@ package attrmapper
 
 import (
 	"github.com/hashicorp/terraform-plugin-codegen-openapi/internal/explorer"
+	"github.com/hashicorp/terraform-plugin-codegen-openapi/internal/mapper/util"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/datasource"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/provider"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/resource"
@@ -38,7 +39,7 @@ func (a *ResourceFloat64Attribute) ApplyOverride(override explorer.Override) (Re
 
 func (a *ResourceFloat64Attribute) ToSpec() resource.Attribute {
 	return resource.Attribute{
-		Name:    a.Name,
+		Name:    util.TerraformIdentifier(a.Name),
 		Float64: &a.Float64Attribute,
 	}
 }
@@ -71,7 +72,7 @@ func (a *DataSourceFloat64Attribute) ApplyOverride(override explorer.Override) (
 
 func (a *DataSourceFloat64Attribute) ToSpec() datasource.Attribute {
 	return datasource.Attribute{
-		Name:    a.Name,
+		Name:    util.TerraformIdentifier(a.Name),
 		Float64: &a.Float64Attribute,
 	}
 }
@@ -84,7 +85,7 @@ type ProviderFloat64Attribute struct {
 
 func (a *ProviderFloat64Attribute) ToSpec() provider.Attribute {
 	return provider.Attribute{
-		Name:    a.Name,
+		Name:    util.TerraformIdentifier(a.Name),
 		Float64: &a.Float64Attribute,
 	}
 }

internal/mapper/attrmapper/int64.go

@@ -5,6 +5,7 @@ package attrmapper
 
 import (
 	"github.com/hashicorp/terraform-plugin-codegen-openapi/internal/explorer"
+	"github.com/hashicorp/terraform-plugin-codegen-openapi/internal/mapper/util"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/datasource"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/provider"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/resource"
@@ -38,7 +39,7 @@ func (a *ResourceInt64Attribute) ApplyOverride(override explorer.Override) (Reso
 
 func (a *ResourceInt64Attribute) ToSpec() resource.Attribute {
 	return resource.Attribute{
-		Name:  a.Name,
+		Name:  util.TerraformIdentifier(a.Name),
 		Int64: &a.Int64Attribute,
 	}
 }
@@ -71,7 +72,7 @@ func (a *DataSourceInt64Attribute) ApplyOverride(override explorer.Override) (Da
 
 func (a *DataSourceInt64Attribute) ToSpec() datasource.Attribute {
 	return datasource.Attribute{
-		Name:  a.Name,
+		Name:  util.TerraformIdentifier(a.Name),
 		Int64: &a.Int64Attribute,
 	}
 }
@@ -84,7 +85,7 @@ type ProviderInt64Attribute struct {
 
 func (a *ProviderInt64Attribute) ToSpec() provider.Attribute {
 	return provider.Attribute{
-		Name:  a.Name,
+		Name:  util.TerraformIdentifier(a.Name),
 		Int64: &a.Int64Attribute,
 	}
 }

internal/mapper/attrmapper/list.go

@@ -5,6 +5,7 @@ package attrmapper
 
 import (
 	"github.com/hashicorp/terraform-plugin-codegen-openapi/internal/explorer"
+	"github.com/hashicorp/terraform-plugin-codegen-openapi/internal/mapper/util"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/datasource"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/provider"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/resource"
@@ -43,7 +44,7 @@ func (a *ResourceListAttribute) ApplyOverride(override explorer.Override) (Resou
 
 func (a *ResourceListAttribute) ToSpec() resource.Attribute {
 	return resource.Attribute{
-		Name: a.Name,
+		Name: util.TerraformIdentifier(a.Name),
 		List: &a.ListAttribute,
 	}
 }
@@ -81,7 +82,7 @@ func (a *DataSourceListAttribute) ApplyOverride(override explorer.Override) (Dat
 
 func (a *DataSourceListAttribute) ToSpec() datasource.Attribute {
 	return datasource.Attribute{
-		Name: a.Name,
+		Name: util.TerraformIdentifier(a.Name),
 		List: &a.ListAttribute,
 	}
 }
@@ -94,7 +95,7 @@ type ProviderListAttribute struct {
 
 func (a *ProviderListAttribute) ToSpec() provider.Attribute {
 	return provider.Attribute{
-		Name: a.Name,
+		Name: util.TerraformIdentifier(a.Name),
 		List: &a.ListAttribute,
 	}
 }

internal/mapper/attrmapper/list_nested.go

@@ -5,6 +5,7 @@ package attrmapper
 
 import (
 	"github.com/hashicorp/terraform-plugin-codegen-openapi/internal/explorer"
+	"github.com/hashicorp/terraform-plugin-codegen-openapi/internal/mapper/util"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/datasource"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/provider"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/resource"
@@ -55,7 +56,7 @@ func (a *ResourceListNestedAttribute) ToSpec() resource.Attribute {
 	}
 
 	return resource.Attribute{
-		Name:       a.Name,
+		Name:       util.TerraformIdentifier(a.Name),
 		ListNested: &a.ListNestedAttribute,
 	}
 }
@@ -105,7 +106,7 @@ func (a *DataSourceListNestedAttribute) ToSpec() datasource.Attribute {
 	}
 
 	return datasource.Attribute{
-		Name:       a.Name,
+		Name:       util.TerraformIdentifier(a.Name),
 		ListNested: &a.ListNestedAttribute,
 	}
 }
@@ -123,7 +124,7 @@ func (a *ProviderListNestedAttribute) ToSpec() provider.Attribute {
 	}
 
 	return provider.Attribute{
-		Name:       a.Name,
+		Name:       util.TerraformIdentifier(a.Name),
 		ListNested: &a.ListNestedAttribute,
 	}
 }

internal/mapper/attrmapper/map.go

@@ -5,6 +5,7 @@ package attrmapper
 
 import (
 	"github.com/hashicorp/terraform-plugin-codegen-openapi/internal/explorer"
+	"github.com/hashicorp/terraform-plugin-codegen-openapi/internal/mapper/util"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/datasource"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/provider"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/resource"
@@ -43,7 +44,7 @@ func (a *ResourceMapAttribute) ApplyOverride(override explorer.Override) (Resour
 
 func (a *ResourceMapAttribute) ToSpec() resource.Attribute {
 	return resource.Attribute{
-		Name: a.Name,
+		Name: util.TerraformIdentifier(a.Name),
 		Map:  &a.MapAttribute,
 	}
 }
@@ -81,7 +82,7 @@ func (a *DataSourceMapAttribute) ApplyOverride(override explorer.Override) (Data
 
 func (a *DataSourceMapAttribute) ToSpec() datasource.Attribute {
 	return datasource.Attribute{
-		Name: a.Name,
+		Name: util.TerraformIdentifier(a.Name),
 		Map:  &a.MapAttribute,
 	}
 }
@@ -94,7 +95,7 @@ type ProviderMapAttribute struct {
 
 func (a *ProviderMapAttribute) ToSpec() provider.Attribute {
 	return provider.Attribute{
-		Name: a.Name,
+		Name: util.TerraformIdentifier(a.Name),
 		Map:  &a.MapAttribute,
 	}
 }

internal/mapper/attrmapper/map_nested.go

@@ -5,6 +5,7 @@ package attrmapper
 
 import (
 	"github.com/hashicorp/terraform-plugin-codegen-openapi/internal/explorer"
+	"github.com/hashicorp/terraform-plugin-codegen-openapi/internal/mapper/util"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/datasource"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/provider"
 	"github.com/hashicorp/terraform-plugin-codegen-spec/resource"
@@ -55,7 +56,7 @@ func (a *ResourceMapNestedAttribute) ToSpec() resource.Attribute {
 	}
 
 	return resource.Attribute{
-		Name:      a.Name,
+		Name:      util.TerraformIdentifier(a.Name),
 		MapNested: &a.MapNestedAttribute,
 	}
 }
@@ -105,7 +106,7 @@ func (a *DataSourceMapNestedAttribute) ToSpec() datasource.Attribute {
 	}
 
 	return datasource.Attribute{
-		Name:      a.Name,
+		Name:      util.TerraformIdentifier(a.Name),
 		MapNested: &a.MapNestedAttribute,
 	}
 }
@@ -123,7 +124,7 @@ func (a *ProviderMapNestedAttribute) ToSpec() provider.Attribute {
 	}
 
 	return provider.Attribute{
-		Name:      a.Name,
+		Name:      util.TerraformIdentifier(a.Name),
 		MapNested: &a.MapNestedAttribute,
 	}
 }