schema-methods.mdx

page_title	description
Home - Plugin Development	Plugin Development is a section for content dedicated to developing Plugins to extend Terraform's core offering.

Terraform Schemas Methods

NOTE should distinguish between schema.Provider, schema.Resource, schema.Schema

Schema methods from schema.Schema:

// If one of these is set, then this item can come from the configuration.
// Both cannot be set. If Optional is set, the value is optional. If
// Required is set, the value is required.
//
// One of these must be set if the value is not computed. That is:
// value either comes from the config, is computed, or is both.
Optional bool
Required bool

// If this is non-nil, the provided function will be used during diff
// of this field. If this is nil, a default diff for the type of the
// schema will be used.
//
// This allows comparison based on something other than primitive, list
// or map equality - for example SSH public keys may be considered
// equivalent regardless of trailing whitespace.
DiffSuppressFunc SchemaDiffSuppressFunc

// If this is non-nil, then this will be a default value that is used
// when this item is not set in the configuration.
//
// DefaultFunc can be specified to compute a dynamic default.
// Only one of Default or DefaultFunc can be set. If DefaultFunc is
// used then its return value should be stable to avoid generating
// confusing/perpetual diffs.
//
// Changing either Default or the return value of DefaultFunc can be
// a breaking change, especially if the attribute in question has
// ForceNew set. If a default needs to change to align with changing
// assumptions in an upstream API then it may be necessary to also use
// the MigrateState function on the resource to change the state to match,
// or have the Read function adjust the state value to align with the
// new default.
//
// If Required is true above, then Default cannot be set. DefaultFunc
// can be set with Required. If the DefaultFunc returns nil, then there
// will be no default and the user will be asked to fill it in.
//
// If either of these is set, then the user won't be asked for input
// for this key if the default is not nil.
Default     interface{}
DefaultFunc SchemaDefaultFunc

// Description is used as the description for docs or asking for user
// input. It should be relatively short (a few sentences max) and should
// be formatted to fit a CLI.
Description string

// InputDefault is the default value to use for when inputs are requested.
// This differs from Default in that if Default is set, no input is
// asked for. If Input is asked, this will be the default value offered.
InputDefault string

// The fields below relate to diffs.
//
// If Computed is true, then the result of this value is computed
// (unless specified by config) on creation.
//
// If ForceNew is true, then a change in this resource necessitates
// the creation of a new resource.
//
// StateFunc is a function called to change the value of this before
// storing it in the state (and likewise before comparing for diffs).
// The use for this is for example with large strings, you may want
// to simply store the hash of it.
Computed  bool
ForceNew  bool
StateFunc SchemaStateFunc

// The following fields are only set for a TypeList, TypeSet, or TypeMap.
//
// Elem represents the element type. For a TypeMap, it must be a *Schema
// with a Type of TypeString, otherwise it may be either a *Schema or a
// *Resource. If it is *Schema, the element type is just a simple value.
// If it is *Resource, the element type is a complex structure,
// potentially with its own lifecycle.
Elem interface{}

// The following fields are only set for a TypeList or TypeSet.
//
// MaxItems defines a maximum amount of items that can exist within a
// TypeSet or TypeList. Specific use cases would be if a TypeSet is being
// used to wrap a complex structure, however more than one instance would
// cause instability.
//
// MinItems defines a minimum amount of items that can exist within a
// TypeSet or TypeList. Specific use cases would be if a TypeSet is being
// used to wrap a complex structure, however less than one instance would
// cause instability.
//
// PromoteSingle, if true, will allow single elements to be standalone
// and promote them to a list. For example "foo" would be promoted to
// ["foo"] automatically. This is primarily for legacy reasons and the
// ambiguity is not recommended for new usage. Promotion is only allowed
// for primitive element types.
MaxItems      int
MinItems      int
PromoteSingle bool

// The following fields are only valid for a TypeSet type.
//
// Set defines a function to determine the unique ID of an item so that
// a proper set can be built.
Set SchemaSetFunc

// ComputedWhen is a set of queries on the configuration. Whenever any
// of these things is changed, it will require a recompute (this requires
// that Computed is set to true).
//
// NOTE: This currently does not work.
ComputedWhen []string

// ConflictsWith is a set of schema keys that conflict with this schema.
// This will only check that they're set in the _config_. This will not
// raise an error for a malfunctioning resource that sets a conflicting
// key.
ConflictsWith []string

// When Deprecated is set, this attribute is deprecated and a warning
// diagnostic will automatically be raised when it is configured.
//
// A deprecated field still works, but will probably stop working in near
// future. This string is the message shown to the user with instructions on
// how to address the deprecation.
//
// In Terraform 1.2.7 and later, this warning diagnostic is displayed any
// time a practitioner attempts to configure a known value for this
// attribute and certain scenarios where this attribute is referenced.
//
// In Terraform 1.2.6 and earlier, this warning diagnostic is only
// displayed when the attribute is Required or Optional, and if the
// practitioner configuration attempts to set the attribute value to a
// known value. It cannot detect practitioner configuration values that
// are unknown ("known after apply").
Deprecated string

// When Removed is set, this attribute has been removed from the schema
//
// Removed attributes can be left in the Schema to generate informative error
// messages for the user when they show up in resource configurations.
// This string is the message shown to the user with instructions on
// what do to about the removed attribute.
Removed string

// ValidateFunc allows individual fields to define arbitrary validation
// logic. It is yielded the provided config value as an interface{} that is
// guaranteed to be of the proper Schema type, and it can yield warnings or
// errors based on inspection of that value.
//
// ValidateFunc currently only works for primitive types.
ValidateFunc SchemaValidateFunc

// Sensitive ensures that the attribute's value does not get displayed in
// logs or regular output. It should be used for passwords or other
// secret fields. Future versions of Terraform may encrypt these
// values.
Sensitive bool