Documentation
¶
Overview ¶
Package mapper provides reflection-based conversion between Terraform Plugin Framework model types and Go SDK request/response types, eliminating repetitive null-check-then-set boilerplate in resource CRUD handlers.
ToSDK copies a model onto an SDK request through its Set{Name} methods, and FromSDK copies an SDK response onto a model through its Get{Name} methods. Field names come from the model's `tfsdk` tags: "allow_query_params" maps to SetAllowQueryParams / GetAllowQueryParams.
Supported attributes ¶
- Scalars: types.String, types.Bool, types.Int64 (to any signed integer setter), types.Float64.
- String lists: types.List of strings ↔ []string.
- Nested objects: a SingleNestedAttribute (a generated *Value type or a plain types.Object) ↔ an SDK struct or pointer to struct. The object's attributes are mapped recursively with the same rules, so nested objects, lists and JSON strings inside it work too.
- Lists of nested objects: a ListNestedAttribute (types.List whose elements are objects) ↔ an SDK slice of structs or struct pointers.
- JSON strings: see below.
Other attribute types (maps, sets, numbers, integer lists) are skipped without a warning; the caller maps them by hand.
JSON-string attributes ¶
A free-form SDK field (interface{}, map[string]interface{}, []interface{}, []map[string]interface{} and similar) has no fixed schema, so the Terraform schema models it as a types.String holding a JSON document. The mapper recognises such a field by the pairing of types, with no tag or option: a types.String attribute whose SDK setter or getter uses a free-form type is treated as JSON.
- ToSDK decodes the string with encoding/json into the setter's type. Invalid JSON is reported as an error diagnostic.
- FromSDK encodes the getter's value in canonical form (object keys sorted, no insignificant whitespace). If the model already holds a JSON string that is semantically equal, that string is kept as is, so a configuration written with different key order or formatting shows no diff and does not trip Terraform's "inconsistent result after apply" check.
Null, unknown and absent values ¶
ToSDK never calls a setter for a null or unknown value, at any depth.
For nested objects, lists of nested objects and JSON strings, FromSDK sets the attribute to null when the SDK reports the field as absent: the getter returns a nil pointer, map, slice or interface, or a Has{Name} method returns false. Attributes of a nested object that have no SDK getter keep the value they had in the model (null if the model had none), so FromSDK should be given the plan or state model, as CRUD handlers already do. That prior value also supplies the element type of a list of nested objects, which a zero types.List does not carry.
Fields the caller maps itself ¶
Both functions accept callerHandled tfsdk tags. Those top-level fields are skipped entirely, so the caller's own mapping is not overwritten and does not produce a misleading "type mismatch" warning.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FromSDK ¶
func FromSDK(ctx context.Context, sdkResp any, tfModel any, callerHandled ...string) diag.Diagnostics
FromSDK maps fields from an SDK response object (sdkResp) back to a Terraform model struct (tfModel) using reflection. For each exported field in tfModel that has a `tfsdk` struct tag, it looks for a corresponding Get{PascalCase}() method on sdkResp. If the getter exists and returns a supported type, the return value is converted to the appropriate Terraform Plugin Framework type and set on the model field.
Supported getter return types: string, bool, int32/int/int64, float32/float64, []string, and the nested object, nested list and JSON forms described in the package documentation. Getters must take no arguments and return a single value.
tfModel must be a pointer so that fields can be set via reflection.
callerHandled names tfsdk tags that the caller maps itself. The mapper leaves those fields untouched.
func ToSDK ¶
ToSDK maps fields from a Terraform model struct (tfModel) to an SDK request object (sdkReq) using reflection. For each exported field in tfModel that has a `tfsdk` struct tag, it looks for a corresponding Set{PascalCase} method on sdkReq. If the TF value is neither null nor unknown, the setter is called with the Go-native value.
See the package documentation for the supported attribute types, including nested objects, lists of nested objects and JSON strings.
sdkReq must be a pointer so that setter methods with pointer receivers are found by reflection.
callerHandled names tfsdk tags that the caller maps itself. The mapper skips those fields without a warning. Use it for fields the mapper cannot convert, such as integer lists, or that need custom logic, so that the caller's own mapping is not overwritten or reported as a type mismatch on every apply.
Types ¶
This section is empty.
Source Files