Consider allowing extension of the provider code specification

Context

As the code generation ecosystem grows with more use-cases it's likely that tools will want to store additional data that may not be applicable to Terraform concepts, but rather, specific to a generating/consuming tool (like OpenAPI).

Currently, the provider code specification does not allow additional fields certain levels of the schema, with the usage of additionalProperties: false:

{
  // ...
  "datasource_string_attribute": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "name": {
        "$ref": "#/$defs/valid_identifier"
      },
      "string": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          // allowed properties
        },
        "required": [
          "computed_optional_required"
        ]
      }
    }
  }
}

Proposal

We don't want to remove this restriction completely, but we should add a designated prefix for custom fields and document it's intended use. We could follow OpenAPI's pattern of allowing properties prefixed with x- at different levels of the schema such as:

Root level, sibling to version string and resources/datasources/provider objects
Sibling to the attribute data (name, {type})
Sibling to the resource/data source/provider schema

Example w/ Petstore

{
  "provider": {
    "name": "petstore"
  },
  "resources": [
    {
      "name": "pet",
      "schema": {
        "attributes": [
          {
            "name": "photo_urls",
            "x-tfplugingen-openapi": {
              // This is the original OpenAPI spec property name
              "oas_property": "photoURLs",
              // This is the OpenAPI type format, for denoting specific types of data
              "oas_format": "date-time"
            },
            "list": {
              "computed_optional_required": "required",
              "element_type": {
                "string": {}
              }
            }
          }
        ]
      }
    }
  ],
  "version": "0.1"
}

hashicorp / terraform-plugin-codegen-spec