modify `terraform providers schema -json` to include fields for `default`, `plan_modifiers`, and `validators`

[drewmullen]

Terraform Version

latest

Use Cases

I want to improve the documentation generated from: https://github.com/hashicorp/terraform-plugin-docs

Attempted Solutions

you can jam a lot of information in to the description field

Proposal

the json schema generated from a provider / resource schema should include information information on:

• default
• plan_modifiers
• validators

"resource_schemas": {
  "resource_name": {
    "version": 0,
    "block": {
      "attributes": {
        "type": {
          "type": "string",
          "description_kind": "plain",
          "optional": true,

          # new fields to add to schema
          "default": "default",
          "validators": [
            "validator description 1"
          ],
          "plan_modifers": [
            "plan mod description 1"
          ]
        }
      },

The plan modifiers could pull from descriptions provided by each. ex: https://github.com/hashicorp/terraform-plugin-framework/blob/main/resource/schema/stringplanmodifier/requires_replace.go#L27

Validators also seem to have the concept: https://github.com/hashicorp/terraform-plugin-framework-validators/blob/main/stringvalidator/any.go#L46

References

• https://github.com/hashicorp/terraform-plugin-docs/issues/398

[crw]

Thanks for this feature request! If you are viewing this issue and would like to indicate your interest, please use the 👍 reaction on the issue description to upvote this issue. We also welcome additional use case descriptions. Thanks again!

[jbardin]

@drewmullen,

Thanks for filing the issue. Things like validators, plan modifiers, or even defaults are all essentially abstract actions that a provider takes based on various configuration parameters, not concrete values that can be represented in the schema. Since what you are looking for is more for documentation rather than data handling, and is outside of the control of the Terraform CLI, we can track the issue in the referenced framework issue rather than here.

Thanks!

[drewmullen]

@jbardin I appreciate your input.

Since what you are looking for is more for documentation... ...outside of the control of the Terraform CLI

If i may ask a clarifying quesiton: yes, they are descriptions but those are programmatically available to the schema from the providers / validators. The CLI is the tool that coordinates the providers, where else would this possibly be implemented? Users would like programatic information about the resources included in a provider...

Perhaps the purpose of the schema isn't clear to me... To me, the schema should communicate relevant information about the resource's schemas. Today it does that but is missing a significant amount of information

[jbardin]

The schema is used by the CLI for type information, including function signatures. Terraform is essentially a statically typed language, and needs that metadata to manipulate, encode and decode the configuration and state values. This happens to give a good starting point for documentation generation, but its intended purpose was not for documentation. Some additions were made to assist in documentation generation, but in the long run a more extensible design needs to be created.

Having this be driven by the developer experience team working on the provider framework makes sure the additions are reflective of their needs first, and can be implemented outside of the core CLI if possible. If there are changes useful to have the core CLI, we can integrated those into the plugin protocol as expose them needed.

[github-actions[bot]]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues. If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.