configschema

Documentation

Overview

Package configschema contains types for describing the expected structure of a configuration block whose shape is not known until runtime.

For example, this is used to describe the expected contents of a resource configuration block, which is defined by the corresponding provider plugin and thus not compiled into Terraform core.

A configschema primarily describes the shape of configuration, but it is also suitable for use with other structures derived from the configuration, such as the cached state of a resource or a resource diff.

This package should not be confused with the package helper/schema, which is the higher-level helper library used to implement providers themselves.

Index

• type Attribute
• type Block
  • func (b *Block) DecoderSpec() hcldec.Spec
  • func (b *Block) ImpliedType() cty.Type
  • func (b *Block) InternalValidate() error
• type NestedBlock
• type NestingMode
  • func (i NestingMode) String() string

Types

type Attribute

type Attribute struct {
	// Type is a type specification that the attribute's value must conform to.
	Type cty.Type

	// Required, if set to true, specifies that an omitted or null value is
	// not permitted.
	Required bool

	// Optional, if set to true, specifies that an omitted or null value is
	// permitted. This field conflicts with Required.
	Optional bool

	// Computed, if set to true, specifies that the value comes from the
	// provider rather than from configuration. If combined with Optional,
	// then the config may optionally provide an overridden value.
	Computed bool

	// Sensitive, if set to true, indicates that an attribute may contain
	// sensitive information.
	//
	// At present nothing is done with this information, but callers are
	// encouraged to set it where appropriate so that it may be used in the
	// future to help Terraform mask sensitive information. (Terraform
	// currently achieves this in a limited sense via other mechanisms.)
	Sensitive bool
}

Attribute represents a configuration attribute, within a block.

type Block

type Block struct {
	// Attributes describes any attributes that may appear directly inside
	// the block.
	Attributes map[string]*Attribute

	// BlockTypes describes any nested block types that may appear directly
	// inside the block.
	BlockTypes map[string]*NestedBlock
}

Block represents a configuration block.

"Block" here is a logical grouping construct, though it happens to map directly onto the physical block syntax of Terraform's native configuration syntax. It may be a more a matter of convention in other syntaxes, such as JSON.

When converted to a value, a Block always becomes an instance of an object type derived from its defined attributes and nested blocks

func (*Block) DecoderSpec

func (b *Block) DecoderSpec() hcldec.Spec

DecoderSpec returns a hcldec.Spec that can be used to decode a HCL Body using the facilities in the hcldec package.

The returned specification is guaranteed to return a value of the same type returned by method ImpliedType, but it may contain null or unknown values if any of the block attributes are defined as optional and/or computed respectively.

func (*Block) ImpliedType

func (b *Block) ImpliedType() cty.Type

ImpliedType returns the cty.Type that would result from decoding a configuration block using the receiving block schema.

ImpliedType always returns a result, even if the given schema is inconsistent. Code that creates configschema.Block objects should be tested using the InternalValidate method to detect any inconsistencies that would cause this method to fall back on defaults and assumptions.

func (*Block) InternalValidate

func (b *Block) InternalValidate() error

InternalValidate returns an error if the receiving block and its child schema definitions have any consistencies with the documented rules for valid schema.

This is intended to be used within unit tests to detect when a given schema is invalid.

type NestedBlock

type NestedBlock struct {
	// Block is the description of the block that's nested.
	Block

	// Nesting provides the nesting mode for the child block, which determines
	// how many instances of the block are allowed, how many labels it expects,
	// and how the resulting data will be converted into a data structure.
	Nesting NestingMode

	// MinItems and MaxItems set, for the NestingList and NestingSet nesting
	// modes, lower and upper limits on the number of child blocks allowed
	// of the given type. If both are left at zero, no limit is applied.
	//
	// As a special case, both values can be set to 1 for NestingSingle in
	// order to indicate that a particular single block is required.
	//
	// These fields are ignored for other nesting modes and must both be left
	// at zero.
	MinItems, MaxItems int
}

NestedBlock represents the embedding of one block within another.

type NestingMode

type NestingMode int

NestingMode is an enumeration of modes for nesting blocks inside other blocks.

const (

	// NestingSingle indicates that only a single instance of a given
	// block type is permitted, with no labels, and its content should be
	// provided directly as an object value.
	NestingSingle NestingMode

	// NestingList indicates that multiple blocks of the given type are
	// permitted, with no labels, and that their corresponding objects should
	// be provided in a list.
	NestingList

	// NestingSet indicates that multiple blocks of the given type are
	// permitted, with no labels, and that their corresponding objects should
	// be provided in a set.
	NestingSet

	// NestingMap indicates that multiple blocks of the given type are
	// permitted, each with a single label, and that their corresponding
	// objects should be provided in a map whose keys are the labels.
	//
	// It's an error, therefore, to use the same label value on multiple
	// blocks.
	NestingMap
)

func (NestingMode) String

func (i NestingMode) String() string