github.com/terramate-io/tf@v0.0.0-20230830114523-fce866b4dfcd/configs/configschema/schema.go (about) 1 // Copyright (c) HashiCorp, Inc. 2 // SPDX-License-Identifier: MPL-2.0 3 4 package configschema 5 6 import ( 7 "github.com/zclconf/go-cty/cty" 8 ) 9 10 type StringKind int 11 12 const ( 13 StringPlain StringKind = iota 14 StringMarkdown 15 ) 16 17 // Block represents a configuration block. 18 // 19 // "Block" here is a logical grouping construct, though it happens to map 20 // directly onto the physical block syntax of Terraform's native configuration 21 // syntax. It may be a more a matter of convention in other syntaxes, such as 22 // JSON. 23 // 24 // When converted to a value, a Block always becomes an instance of an object 25 // type derived from its defined attributes and nested blocks 26 type Block struct { 27 // Attributes describes any attributes that may appear directly inside 28 // the block. 29 Attributes map[string]*Attribute 30 31 // BlockTypes describes any nested block types that may appear directly 32 // inside the block. 33 BlockTypes map[string]*NestedBlock 34 35 Description string 36 DescriptionKind StringKind 37 38 Deprecated bool 39 } 40 41 // Attribute represents a configuration attribute, within a block. 42 type Attribute struct { 43 // Type is a type specification that the attribute's value must conform to. 44 // It conflicts with NestedType. 45 Type cty.Type 46 47 // NestedType indicates that the attribute is a NestedBlock-style object. 48 // This field conflicts with Type. 49 NestedType *Object 50 51 // Description is an English-language description of the purpose and 52 // usage of the attribute. A description should be concise and use only 53 // one or two sentences, leaving full definition to longer-form 54 // documentation defined elsewhere. 55 Description string 56 DescriptionKind StringKind 57 58 // Required, if set to true, specifies that an omitted or null value is 59 // not permitted. 60 Required bool 61 62 // Optional, if set to true, specifies that an omitted or null value is 63 // permitted. This field conflicts with Required. 64 Optional bool 65 66 // Computed, if set to true, specifies that the value comes from the 67 // provider rather than from configuration. If combined with Optional, 68 // then the config may optionally provide an overridden value. 69 Computed bool 70 71 // Sensitive, if set to true, indicates that an attribute may contain 72 // sensitive information. 73 // 74 // At present nothing is done with this information, but callers are 75 // encouraged to set it where appropriate so that it may be used in the 76 // future to help Terraform mask sensitive information. (Terraform 77 // currently achieves this in a limited sense via other mechanisms.) 78 Sensitive bool 79 80 Deprecated bool 81 } 82 83 // Object represents the embedding of a structural object inside an Attribute. 84 type Object struct { 85 // Attributes describes the nested attributes which may appear inside the 86 // Object. 87 Attributes map[string]*Attribute 88 89 // Nesting provides the nesting mode for this Object, which determines how 90 // many instances of the Object are allowed, how many labels it expects, and 91 // how the resulting data will be converted into a data structure. 92 Nesting NestingMode 93 } 94 95 // NestedBlock represents the embedding of one block within another. 96 type NestedBlock struct { 97 // Block is the description of the block that's nested. 98 Block 99 100 // Nesting provides the nesting mode for the child block, which determines 101 // how many instances of the block are allowed, how many labels it expects, 102 // and how the resulting data will be converted into a data structure. 103 Nesting NestingMode 104 105 // MinItems and MaxItems set, for the NestingList and NestingSet nesting 106 // modes, lower and upper limits on the number of child blocks allowed 107 // of the given type. If both are left at zero, no limit is applied. 108 // 109 // As a special case, both values can be set to 1 for NestingSingle in 110 // order to indicate that a particular single block is required. 111 // 112 // These fields are ignored for other nesting modes and must both be left 113 // at zero. 114 MinItems, MaxItems int 115 } 116 117 // NestingMode is an enumeration of modes for nesting blocks inside other 118 // blocks. 119 type NestingMode int 120 121 // Object represents the embedding of a NestedBl 122 123 //go:generate go run golang.org/x/tools/cmd/stringer -type=NestingMode 124 125 const ( 126 nestingModeInvalid NestingMode = iota 127 128 // NestingSingle indicates that only a single instance of a given 129 // block type is permitted, with no labels, and its content should be 130 // provided directly as an object value. 131 NestingSingle 132 133 // NestingGroup is similar to NestingSingle in that it calls for only a 134 // single instance of a given block type with no labels, but it additonally 135 // guarantees that its result will never be null, even if the block is 136 // absent, and instead the nested attributes and blocks will be treated 137 // as absent in that case. (Any required attributes or blocks within the 138 // nested block are not enforced unless the block is explicitly present 139 // in the configuration, so they are all effectively optional when the 140 // block is not present.) 141 // 142 // This is useful for the situation where a remote API has a feature that 143 // is always enabled but has a group of settings related to that feature 144 // that themselves have default values. By using NestingGroup instead of 145 // NestingSingle in that case, generated plans will show the block as 146 // present even when not present in configuration, thus allowing any 147 // default values within to be displayed to the user. 148 NestingGroup 149 150 // NestingList indicates that multiple blocks of the given type are 151 // permitted, with no labels, and that their corresponding objects should 152 // be provided in a list. 153 NestingList 154 155 // NestingSet indicates that multiple blocks of the given type are 156 // permitted, with no labels, and that their corresponding objects should 157 // be provided in a set. 158 NestingSet 159 160 // NestingMap indicates that multiple blocks of the given type are 161 // permitted, each with a single label, and that their corresponding 162 // objects should be provided in a map whose keys are the labels. 163 // 164 // It's an error, therefore, to use the same label value on multiple 165 // blocks. 166 NestingMap 167 )