helper/schema: allow Schema attrs to be Removed

Removed fields show a customizable error message to the user when they
are used in a Terraform config. This is a tool that provider authors can
use for user feedback as they evolve their Schemas.

refs #957

helper/schema/schema.go

@@ -114,12 +114,20 @@ type Schema struct {
 	// NOTE: This currently does not work.
 	ComputedWhen []string
 
-	// When Deprecated is set, this field is deprecated.
+	// When Deprecated is set, this attribute is deprecated.
 	//
 	// A deprecated field still works, but will probably stop working in near
 	// future. This string is the message shown to the user with instructions on
 	// how to address the deprecation.
 	Deprecated string
+
+	// When Removed is set, this attribute has been removed from the schema
+	//
+	// Removed attributes can be left in the Schema to generate informative error
+	// messages for the user when they show up in resource configurations.
+	// This string is the message shown to the user with instructions on
+	// what do to about the removed attribute.
+	Removed string
 }
 
 // SchemaDefaultFunc is a function called to return a default value for
@@ -1091,6 +1099,11 @@ func (m schemaMap) validateType(
 			"%q: [DEPRECATED] %s", k, schema.Deprecated))
 	}
 
+	if schema.Removed != "" {
+		es = append(es, fmt.Errorf(
+			"%q: [REMOVED] %s", k, schema.Removed))
+	}
+
 	return ws, es
 }
 

helper/schema/schema_test.go

@@ -2588,6 +2588,7 @@ func TestSchemaMap_Validate(t *testing.T) {
 		Config   map[string]interface{}
 		Vars     map[string]string
 		Err      bool
+		Errors   []error
 		Warnings []string
 	}{
 		"Good": {
@@ -3054,47 +3055,35 @@ func TestSchemaMap_Validate(t *testing.T) {
 			Warnings: nil,
 		},
 
-		"Deprecated works with set/list type": {
+		"Removed attribute usage generates error": {
 			Schema: map[string]*Schema{
-				"old_news": &Schema{
-					Type:       TypeSet,
-					Optional:   true,
-					Elem:       &Schema{Type: TypeString},
-					Deprecated: "please use 'new_news' instead",
+				"long_gone": &Schema{
+					Type:     TypeString,
+					Optional: true,
+					Removed:  "no longer supported by Cloud API",
 				},
 			},
 
 			Config: map[string]interface{}{
-				"old_news": []interface{}{"extra extra!"},
+				"long_gone": "still here!",
 			},
 
-			Err: false,
-
-			Warnings: []string{
-				"\"old_news\": [DEPRECATED] please use 'new_news' instead",
+			Err: true,
+			Errors: []error{
+				fmt.Errorf("\"long_gone\": [REMOVED] no longer supported by Cloud API"),
 			},
 		},
 
-		"Deprecated works with map type": {
+		"Removed generates no errors if attr not used": {
 			Schema: map[string]*Schema{
-				"old_news": &Schema{
-					Type:       TypeMap,
-					Optional:   true,
-					Deprecated: "please use 'new_news' instead",
-				},
-			},
-
-			Config: map[string]interface{}{
-				"old_news": map[string]interface{}{
-					"foo": "bar",
+				"long_gone": &Schema{
+					Type:     TypeString,
+					Optional: true,
+					Removed:  "no longer supported by Cloud API",
 				},
 			},
 
 			Err: false,
-
-			Warnings: []string{
-				"\"old_news\": [DEPRECATED] please use 'new_news' instead",
-			},
 		},
 	}
 
@@ -3130,5 +3119,11 @@ func TestSchemaMap_Validate(t *testing.T) {
 		if !reflect.DeepEqual(ws, tc.Warnings) {
 			t.Fatalf("%q: warnings:\n\nexpected: %#v\ngot:%#v", tn, tc.Warnings, ws)
 		}
+
+		if tc.Errors != nil {
+			if !reflect.DeepEqual(es, tc.Errors) {
+				t.Fatalf("%q: errors:\n\nexpected: %q\ngot: %q", tn, tc.Errors, es)
+			}
+		}
 	}
 }