Support for `oneOf` with discriminator

[romming]

I am looking to create a provider for an API that makes heavy use of polymorphism, i.e. a oneOf with a discriminator value. I am aware that this is currently not supported. This post has a couple of ideas for how a provider could support polymorphism.

Is support for this type of polymorphism on your roadmap? If yes, do you have thoughts on what the generated spec would look like? If not, do you have thoughts on alternative approaches?

[austinvalle]

Hey there @romming 👋🏻, thanks for raising this question.

Polymorphism (oneOf / anyOf ) is an area that would be difficult for this code generator to fully support as Terraform's type system doesn't support describing these type constraints, which makes it unlikely that Terraform Plugin Framework would introduce support for this.

Currently, the only possible way to describe an attribute to Terraform that is polymorphic would be to utilize the any constraint, which is essentially an escape hatch, and then implement the detection of types in the provider.

Once Terraform Plugin Framework introduces these dynamic types (issue for tracking) we could potentially mark every oneOf/anyOf constraints as a dynamic attribute, but the actual logic for detecting and handling types would be still need to be determined.

Are you able to share more specifics on the API spec/schema you're trying to create a provider for?

[romming]

Hi @austinvalle - thanks for the quick response!

Understood that there are constraints in Terraform's type system. Here is an example API endpoint I'm looking to create a provider for. Note that e.g. the source field is specified as a oneOf.

I'm new to Terraform plugins, so this may be way off: could we specify each of the oneOf mappings as an optional Single Nested Attribute, and then implement a validation rule that ensures that exactly one of them is set? That way we could use the type system to validate the structure of whichever sub-type is set. The name of the attribute could be something like {{api_attribute_name}}_{{discriminator_value}}.

Curious whether you think this would work, and if so, if it seems like a good approach to mapping oneOfs with discriminators in general.

[austinvalle]

Thanks for sharing the example, that really helps!

We (the maintainers) need to spend some more time thinking if we can fully support oneOf/anyOf by splitting them into sibling attributes and applying validation. While at first thought, that should be technically valid, it is a design choice that may not fit for all use-cases (you could also split each source into it's own resource, which is sometimes recommended for a better UX, which is highly subjective to each use-case). A very interesting problem!

I believe you are correct in thinking that the source property, could be roughly mapped to:

func (r *pipelineResource) ConfigValidators(ctx context.Context) []resource.ConfigValidator {
	return []resource.ConfigValidator{
		resourcevalidator.ExactlyOneOf(
			path.MatchRoot("source_bigquery"),
			path.MatchRoot("source_db2"),
			path.MatchRoot("source_kafka"),
			// other source attributes
		),
	}
}

func (r *pipelineResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
	resp.Schema = schema.Schema{
		Attributes: map[string]schema.Attribute{
			"source_bigquery": schema.SingleNestedAttribute{
				Optional: true,
				Attributes: map[string]schema.Attribute{
					"type": schema.StringAttribute{
						Required: true,
					},
					// bigquery attributes
				},
			},
			"source_db2": schema.SingleNestedAttribute{
				Optional: true,
				Attributes: map[string]schema.Attribute{
					"type": schema.StringAttribute{
						Required: true,
					},
					// db2 attributes
				},
			},
			"source_kafka": schema.SingleNestedAttribute{
				Optional: true,
				Attributes: map[string]schema.Attribute{
					"type": schema.StringAttribute{
						Required: true,
					},
					// kafka attributes
				},
			},
			// other source attributes
		},
	}
}

Using resource config validators wouldn't be something that codegen could currently support (right now we generate just the schema bits).

I believe you could technically implement something similar in just the schema like:

func (r *pipelineResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
	resp.Schema = schema.Schema{
		Attributes: map[string]schema.Attribute{
			"source_bigquery": schema.SingleNestedAttribute{
				Optional: true,
				Validators: []validator.Object{
					objectvalidator.ExactlyOneOf(path.Expressions{
						path.MatchRoot("source_db2"),
						path.MatchRoot("source_kafka"),
					}...),
				},
				Attributes: map[string]schema.Attribute{
					"type": schema.StringAttribute{
						Required: true,
					},
					// bigquery attributes
				},
			},
			"source_db2": schema.SingleNestedAttribute{
				Optional: true,
				Attributes: map[string]schema.Attribute{
					"type": schema.StringAttribute{
						Required: true,
					},
					// db2 attributes
				},
			},
			"source_kafka": schema.SingleNestedAttribute{
				Optional: true,
				Attributes: map[string]schema.Attribute{
					"type": schema.StringAttribute{
						Required: true,
					},
					// kafka attributes
				},
			},
			// other source attributes
		},
	}
}

I'm gonna mark this issue as an enhancement and see if there are more use-cases in the community where splitting into sibling attributes may be desirable for oneOf/anyOf.

[epsilon-0]

Here's another example for pingdom - https://docs.pingdom.com/api/API_3.1.yaml
This too doesn't work with a trivial config like this one

provider:
  name: pingdom

resources:
  check:
    create:
      path: /checks
      method: POST
    read:
      path: /checks/{checkid}
      method: GET
    update:
      path: /checks/{checkid}
      method: PUT
    delete:
      path: /checks/{checkid}
      method: DELETE

[epsilon-0]

Would something like resource blocks not work?

resource "cool_provider" "this" {
  oneOfBlock1 {
    param1 = val1
    ...
  }
  oneOfBlock2 {
    paramX = valX
    ...
  }
  // add validation constraint saying only one block is allowed
}

[austinvalle]

Thanks for providing another example @epsilon-0!

Would something like resource blocks not work?

The potential solution above in #94 (comment) uses nested attributes, but I believe you could achieve something similar with blocks.

[patrickcping]

@austinvalle just to add another example, our provider implements the schema in your example above in quite a few resources. A prime example being the pingone_application.

The API implements a polymorphic request/response object, but we've chosen to implement the oidc_options block to represent an object of type OPENID_CONNECT, the saml_options block to represent an object of SAML etc.

We find this is gets better user feedback when compared with "flat" API structures as we see in pingone_form.components.fields