Update go-cty and improve documentation for optional and default attributes

3 files changed, 24 insertions, 7 deletions

diff --git a/ext/typeexpr/README.md b/ext/typeexpr/README.md
index 058f1e3..c0fa6ab 100644
--- a/ext/typeexpr/README.md
+++ b/ext/typeexpr/README.md
@@ -66,6 +66,27 @@ types with weird attributes generally show up only from arbitrary object
 constructors in configuration files, which are usually treated either as maps
 or as the dynamic pseudo-type.
 
+### Optional Object Attributes
+
+As part of object expressions attributes can be marked as optional. Missing 
+object attributes would typically result in an error when type constraints are
+validated or used. Optional missing attributes, however, would not result in an 
+error. The `cty` ["convert" function](#the-convert-cty-function) will populate 
+missing optional attributes with null values.
+
+For example:
+
+* `object({name=string,age=optional(number)})`
+
+Optional attributes can also be specified with default values. The 
+`TypeConstraintWithDefaults` function will return a `Defaults` object that can
+be used to populate missing optional attributes with defaults in a given 
+`cty.Value`.
+
+For example:
+
+* `object({name=string,age=optional(number, 0)})`
+
 ## Type Constraints as Values
 
 Along with defining a convention for writing down types using HCL expression
diff --git a/ext/typeexpr/defaults.go b/ext/typeexpr/defaults.go
index 851c72f..4e96057 100644
--- a/ext/typeexpr/defaults.go
+++ b/ext/typeexpr/defaults.go
@@ -6,7 +6,7 @@ import (
 
 // Defaults represents a type tree which may contain default values for
 // optional object attributes at any level. This is used to apply nested
-// defaults to an input value before converting it to the concrete type.
+// defaults to a given cty.Value.
 type Defaults struct {
 	// Type of the node for which these defaults apply. This is necessary in
 	// order to determine how to inspect the Defaults and Children collections.
@@ -28,8 +28,8 @@ type Defaults struct {
 
 // Apply walks the given value, applying specified defaults wherever optional
 // attributes are missing. The input and output values may have different
-// types, and the result may still require type conversion to the final desired
-// type.
+// types, to avoid this the input value should be converted into the desired
+// type first.
 //
 // This function is permissive and does not report errors, assuming that the
 // caller will have better context to report useful type conversion failure
diff --git a/ext/typeexpr/public.go b/ext/typeexpr/public.go
index 82f215c..f2e187e 100644
--- a/ext/typeexpr/public.go
+++ b/ext/typeexpr/public.go
@@ -35,10 +35,6 @@ func TypeConstraint(expr hcl.Expression) (cty.Type, hcl.Diagnostics) {
 // constraint which may include default values for object attributes. If
 // successful both the resulting type and corresponding defaults are returned.
 // If unsuccessful, error diagnostics are returned.
-//
-// When using this function, defaults should be applied to the input value
-// before type conversion, to ensure that objects with missing attributes have
-// default values populated.
 func TypeConstraintWithDefaults(expr hcl.Expression) (cty.Type, *Defaults, hcl.Diagnostics) {
 	return getType(expr, true, true)
 }