Configuration Syntax docs aren't clear about complex fields

[rileykarson]

Looking at https://www.terraform.io/docs/configuration/syntax.html, it isn't clear how I would specify a list of non-primitive objects.

Context: hashicorp/terraform-provider-google#2549

[apparentlymart]

This documentation has been revised considerably in preparation for 0.12, so the new version is hopefully clearer. That'll be on the website once 0.12 is released.

"Nested blocks" is the best way to talk about these things in the provider docs, to match how the main docs talk about them. Since users can access these via expressions, it can be helpful to know what appears as a list vs. a set attribute in that context, but the block syntax is intentionally agnostic about what underlying data structure is used so readers can think of them as being distinct objects of the same type, rather than as a collection.

[rileykarson]

Thanks for the canonical name! I'll try and think about how we can incorporate it as we update our docs.

I'm not sure that that page, or any other 0.12 page that I've looked at serves as an effective reference for what configuration will look like in a provider. A page that has examples of each field type (primitives, TypeList, TypeSet, TypeMap etc woukld be a useful resource when explaining some configs - for example, explaining that you can define multiple nested blocks of the same type and they function like a list/set of a complex element, or what map syntax looks like.

For a concrete example, it doesn't look like TypeMaps are covered effectively- to my understanding (based on our failing tests while trying to vendor 0.12), they always require an = now but otherwise mostly look like nested blocks. Based on reading that page, I get the impression that I should have my type then a {; it's unclear why I need to assign a nested block.

[apparentlymart]

So far we've expected users would rather see concrete examples on each resource page rather than a generalized description of how blocks work in theory, but it does seem like we could do a better job in the Extend documentation of describing how the concepts in the SDK map back to the concepts in Terraform itself; historically we got away with being vague about that because Terraform itself was sloppy about it: lots of information was lost on the path between the configuration files and the SDK, so there were potentially many different ways to write the same thing, some of which would behave in buggy ways and cause confusing errors.

In 0.12, the general rule from the SDK perspective is: if Elem is schema.Resource then it's a nested block, and if it's a schema.Schema then it's an attribute. Since the current SDK doesn't support TypeMap with a non-primitive Elem, a TypeMap will always be an attribute today.

The core system does now support nested blocks backed by maps, which have a syntax like this:

block_type "key" {
  # ...
}

...but there's no way to express that in the current SDK, since it's constrained by having to still support Terraform 0.11 where the state serialization has no way to retain such a thing. Support for this will arrive once we begin phasing out support for Terraform 0.11, the schedule for which is not yet determined since we need to make sure the 0.12 upgrade path is in good shape first.

Looking at the SDK docs for aggregate types I see that it doesn't really talk about schema.Schema vs. schema.Resource at all today, and a literal reading of it might mislead someone to think that lists always use schema.Schema while sets always use schema.Resource because the only mention of this is as an aside in the examples. So I think the most important thing to do here is to talk explicitly in those docs about how the Elem field value is interpreted and how that relates back to the configuration language concepts, which can then be used in turn to use the right terminology also in the provider-specific docs when describing configuration constructs.