Merge pull request #250 from Juniper/task/221

Update docs to clarify when either `id` or `name` is required input
Juniper · Aug 6, 2023 · 8ecd8ba · 8ecd8ba
2 parents 256c925 + 6d3541b
commit 8ecd8ba
Show file tree

Hide file tree

Showing 45 changed files with 107 additions and 114 deletions.
diff --git a/apstra/blueprint/blueprint.go b/apstra/blueprint/blueprint.go
@@ -44,7 +44,7 @@ type Blueprint struct {
 func (o Blueprint) DataSourceAttributes() map[string]dataSourceSchema.Attribute {
 	return map[string]dataSourceSchema.Attribute{
 		"id": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "ID of the Blueprint: Either as a result of a lookup, or user-specified.",
+			MarkdownDescription: "ID of the Blueprint. Required when `name` is omitted.",
 			Computed:            true,
 			Optional:            true,
 			Validators: []validator.String{
@@ -56,7 +56,7 @@ func (o Blueprint) DataSourceAttributes() map[string]dataSourceSchema.Attribute
 			},
 		},
 		"name": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Name of the Blueprint: Either as a result of a lookup, or user-specified.",
+			MarkdownDescription: "Name of the Blueprint. Required when `id` is omitted.",
 			Computed:            true,
 			Optional:            true,
 			Validators:          []validator.String{stringvalidator.LengthAtLeast(1)},

diff --git a/apstra/blueprint/datacenter_routing_policy.go b/apstra/blueprint/datacenter_routing_policy.go
@@ -137,7 +137,7 @@ func (o DatacenterRoutingPolicy) ResourceAttributes() map[string]resourceSchema.
 func (o DatacenterRoutingPolicy) DataSourceAttributes() map[string]dataSourceSchema.Attribute {
 	return map[string]dataSourceSchema.Attribute{
 		"id": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Apstra graph node ID.",
+			MarkdownDescription: "Apstra graph node ID. Required when `name` is omitted.",
 			Computed:            true,
 			Optional:            true,
 			Validators: []validator.String{
@@ -149,7 +149,7 @@ func (o DatacenterRoutingPolicy) DataSourceAttributes() map[string]dataSourceSch
 			},
 		},
 		"name": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Web UI `name` field.",
+			MarkdownDescription: "Web UI `name` field. Required when `id` is omitted.",
 			Computed:            true,
 			Optional:            true,
 			Validators:          []validator.String{stringvalidator.LengthBetween(1, 18)},

diff --git a/apstra/blueprint/datacenter_routing_zone.go b/apstra/blueprint/datacenter_routing_zone.go
@@ -43,7 +43,7 @@ func (o DatacenterRoutingZone) DataSourceAttributes() map[string]dataSourceSchem
 	nameRE := regexp.MustCompile("^[A-Za-z0-9_-]+$")
 	return map[string]dataSourceSchema.Attribute{
 		"id": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Apstra graph node ID.",
+			MarkdownDescription: "Apstra graph node ID. Required when `name` is omitted.",
 			Computed:            true,
 			Optional:            true,
 			Validators: []validator.String{
@@ -55,7 +55,7 @@ func (o DatacenterRoutingZone) DataSourceAttributes() map[string]dataSourceSchem
 			},
 		},
 		"blueprint_id": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Apstra Blueprint ID.",
+			MarkdownDescription: "Apstra Blueprint ID. Required when `id` is omitted.",
 			Required:            true,
 			Validators:          []validator.String{stringvalidator.LengthAtLeast(1)},
 		},

diff --git a/apstra/blueprint/node_system.go b/apstra/blueprint/node_system.go
@@ -28,15 +28,15 @@ func (o NodeTypeSystem) DataSourceAttributes() map[string]dataSourceSchema.Attri
 			Required:            true,
 		},
 		"id": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Apstra Graph DB node `id` field",
+			MarkdownDescription: "Apstra Graph DB node `id` field. Required when `name` is omitted.",
 			Optional:            true,
 			Validators: []validator.String{stringvalidator.ExactlyOneOf(path.Expressions{
 				path.MatchRelative(),
 				path.MatchRoot("name"),
 			}...)},
 		},
 		"name": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Apstra Web UI `name` field / Graph DB `label` field",
+			MarkdownDescription: "Apstra Web UI name (Graph DB `label` field). Required when `id` is omitted.",
 			Optional:            true,
 		},
 		"attributes": dataSourceSchema.SingleNestedAttribute{

diff --git a/apstra/data_source_asn_pool.go b/apstra/data_source_asn_pool.go
@@ -29,9 +29,7 @@ func (o *dataSourceAsnPool) Configure(ctx context.Context, req datasource.Config
 func (o *dataSourceAsnPool) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
 		MarkdownDescription: "This data source provides details of a specific ASN Pool.\n\n" +
-			"At least one optional attribute is required. " +
-			"It is incumbent upon the user to ensure the lookup criteria matches exactly one ASN Pool. " +
-			"Matching zero or more ASN Pools will produce an error.",
+			"At least one optional attribute is required.",
 		Attributes: resources.AsnPool{}.DataSourceAttributes(),
 	}
 }

diff --git a/apstra/data_source_configlet.go b/apstra/data_source_configlet.go
@@ -29,7 +29,7 @@ func (o *dataSourceConfiglet) Configure(ctx context.Context, req datasource.Conf
 func (o *dataSourceConfiglet) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
 		MarkdownDescription: "This data source provides details of a specific Configlet.\n\n" +
-			"At least one optional attribute is required. ",
+			"At least one optional attribute is required.",
 		Attributes: design.Configlet{}.DataSourceAttributes(),
 	}
 }

diff --git a/apstra/data_source_datacenter_blueprint.go b/apstra/data_source_datacenter_blueprint.go
@@ -28,9 +28,7 @@ func (o *dataSourceDatacenterBlueprint) Configure(ctx context.Context, req datas
 func (o *dataSourceDatacenterBlueprint) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
 		MarkdownDescription: "This data source looks up summary details of a Datacenter Blueprint.\n\n" +
-			"At least one optional attribute is required. " +
-			"It is incumbent upon the user to ensure the lookup criteria matches exactly one Datacenter Blueprint. " +
-			"Matching zero or more Datacenter Blueprints will produce an error.",
+			"At least one optional attribute is required.",
 		Attributes: blueprint.Blueprint{}.DataSourceAttributes(),
 	}
 }

diff --git a/apstra/data_source_datacenter_property_set.go b/apstra/data_source_datacenter_property_set.go
@@ -28,7 +28,7 @@ func (o *dataSourceDatacenterPropertySet) Configure(ctx context.Context, req dat
 func (o *dataSourceDatacenterPropertySet) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
 		MarkdownDescription: "This data source provides details of a specific Property Set imported into a Blueprint.\n\n" +
-			"At least one optional attribute is required. ",
+			"At least one optional attribute is required.",
 		Attributes: blueprint.DatacenterPropertySet{}.DataSourceAttributes(),
 	}
 }

diff --git a/apstra/data_source_datacenter_routing_policy.go b/apstra/data_source_datacenter_routing_policy.go
@@ -28,8 +28,9 @@ func (o *dataSourceDatacenterRoutingPolicy) Configure(ctx context.Context, req d
 
 func (o *dataSourceDatacenterRoutingPolicy) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		MarkdownDescription: "This resource returns details of a Datacenter Routing Policy.",
-		Attributes:          blueprint.DatacenterRoutingPolicy{}.DataSourceAttributes(),
+		MarkdownDescription: "This resource returns details of a Datacenter Routing Policy.\n\n" +
+			"At least one optional attribute is required.",
+		Attributes: blueprint.DatacenterRoutingPolicy{}.DataSourceAttributes(),
 	}
 }
 

diff --git a/apstra/data_source_datacenter_routing_zone.go b/apstra/data_source_datacenter_routing_zone.go
@@ -29,8 +29,9 @@ func (o *dataSourceDatacenterRoutingZone) Configure(ctx context.Context, req dat
 
 func (o *dataSourceDatacenterRoutingZone) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		MarkdownDescription: "This resource returns details of a Routing Zone within a Datacenter Blueprint.",
-		Attributes:          blueprint.DatacenterRoutingZone{}.DataSourceAttributes(),
+		MarkdownDescription: "This resource returns details of a Routing Zone within a Datacenter Blueprint.\n\n" +
+			"At least one optional attribute is required.",
+		Attributes: blueprint.DatacenterRoutingZone{}.DataSourceAttributes(),
 	}
 }
 

diff --git a/apstra/data_source_datacenter_system.go b/apstra/data_source_datacenter_system.go
@@ -24,8 +24,8 @@ func (o *dataSourceDatacenterSystemNode) Configure(ctx context.Context, req data
 
 func (o *dataSourceDatacenterSystemNode) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		MarkdownDescription: "This data source returns details of a specific " +
-			"*system* Graph DB node within a Blueprint.",
+		MarkdownDescription: "This data source returns details of a specific *system* Graph DB node within a Blueprint.\n\n" +
+			"At least one optional attribute is required.",
 		Attributes: blueprint.NodeTypeSystem{}.DataSourceAttributes(),
 	}
 }

diff --git a/apstra/data_source_interface_map.go b/apstra/data_source_interface_map.go
@@ -29,9 +29,7 @@ func (o *dataSourceInterfaceMap) Configure(ctx context.Context, req datasource.C
 func (o *dataSourceInterfaceMap) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
 		MarkdownDescription: "This data source provides details of a specific Interface Map.\n\n" +
-			"At least one optional attribute is required. " +
-			"It is incumbent upon the user to ensure the lookup criteria matches exactly one Interface Map. " +
-			"Matching zero or more Interface Maps will produce an error.",
+			"At least one optional attribute is required.",
 		Attributes: design.InterfaceMap{}.DataSourceAttributes(),
 	}
 }

diff --git a/apstra/data_source_ipv4_pool.go b/apstra/data_source_ipv4_pool.go
@@ -28,9 +28,7 @@ func (o *dataSourceIpv4Pool) Configure(ctx context.Context, req datasource.Confi
 func (o *dataSourceIpv4Pool) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
 		MarkdownDescription: "This data source provides details of a specific IPv4 Pool.\n\n" +
-			"At least one optional attribute is required. " +
-			"It is incumbent upon the user to ensure the lookup criteria matches exactly one IPv4 Pool. " +
-			"Matching zero or more IPv4 Pools will produce an error.",
+			"At least one optional attribute is required.",
 		Attributes: resources.Ipv4Pool{}.DataSourceAttributes(),
 	}
 }

diff --git a/apstra/data_source_ipv6_pool.go b/apstra/data_source_ipv6_pool.go
@@ -28,9 +28,7 @@ func (o *dataSourceIpv6Pool) Configure(ctx context.Context, req datasource.Confi
 func (o *dataSourceIpv6Pool) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
 		MarkdownDescription: "This data source provides details of a specific IPv6 Pool.\n\n" +
-			"At least one optional attribute is required. " +
-			"It is incumbent upon the user to ensure the lookup criteria matches exactly one IPv6 Pool. " +
-			"Matching zero or more IPv6 Pools will produce an error.",
+			"At least one optional attribute is required.",
 		Attributes: resources.Ipv6Pool{}.DataSourceAttributes(),
 	}
 }

diff --git a/apstra/data_source_logical_device.go b/apstra/data_source_logical_device.go
@@ -29,9 +29,7 @@ func (o *dataSourceLogicalDevice) Configure(ctx context.Context, req datasource.
 func (o *dataSourceLogicalDevice) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
 		MarkdownDescription: "This data source provides details of a specific Logical Device.\n\n" +
-			"At least one optional attribute is required. " +
-			"It is incumbent upon the user to ensure the lookup criteria matches exactly one Logical Device. " +
-			"Matching zero or more Logical Devices will produce an error.",
+			"At least one optional attribute is required.",
 		Attributes: design.LogicalDevice{}.DataSourceAttributes(),
 	}
 }

diff --git a/apstra/data_source_property_set.go b/apstra/data_source_property_set.go
@@ -29,7 +29,7 @@ func (o *dataSourcePropertySet) Configure(ctx context.Context, req datasource.Co
 func (o *dataSourcePropertySet) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
 		MarkdownDescription: "This data source provides details of a specific PropertySet.\n\n" +
-			"At least one optional attribute is required. ",
+			"At least one optional attribute is required.",
 		Attributes: design.PropertySet{}.DataSourceAttributes(),
 	}
 }

diff --git a/apstra/data_source_rack_type.go b/apstra/data_source_rack_type.go
@@ -29,9 +29,7 @@ func (o *dataSourceRackType) Configure(ctx context.Context, req datasource.Confi
 func (o *dataSourceRackType) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
 		MarkdownDescription: "This data source provides details of a specific Rack Type.\n\n" +
-			"At least one optional attribute is required. " +
-			"It is incumbent on the user to ensure the criteria matches exactly one Rack Type. " +
-			"Matching zero Rack Types or more than one Rack Type will produce an error.",
+			"At least one optional attribute is required.",
 		Attributes: design.RackType{}.DataSourceAttributes(),
 	}
 }

diff --git a/apstra/data_source_template_rack_based.go b/apstra/data_source_template_rack_based.go
@@ -28,9 +28,7 @@ func (o *dataSourceTemplateRackBased) Configure(ctx context.Context, req datasou
 func (o *dataSourceTemplateRackBased) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
 		MarkdownDescription: "This data source provides details of a specific Rack Based (3 stage) Template.\n\n" +
-			"At least one optional attribute is required. " +
-			"It is incumbent on the user to ensure the criteria matches exactly one Rack Based Template. " +
-			"Matching zero Rack Based Templates or more than one Rack Based Template will produce an error.",
+			"At least one optional attribute is required.",
 		Attributes: design.TemplateRackBased{}.DataSourceAttributes(),
 	}
 }

diff --git a/apstra/data_source_vni_pool.go b/apstra/data_source_vni_pool.go
@@ -29,9 +29,7 @@ func (o *dataSourceVniPool) Configure(ctx context.Context, req datasource.Config
 func (o *dataSourceVniPool) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
 		MarkdownDescription: "This data source provides details of a specific VNI Pool.\n\n" +
-			"At least one optional attribute is required. " +
-			"It is incumbent upon the user to ensure the lookup criteria matches exactly one VNI Pool. " +
-			"Matching zero or more VNI Pools will produce an error.",
+			"At least one optional attribute is required.",
 		Attributes: resources.VniPool{}.DataSourceAttributes(),
 	}
 }

diff --git a/apstra/design/interface_map.go b/apstra/design/interface_map.go
@@ -22,7 +22,7 @@ type InterfaceMap struct {
 func (o InterfaceMap) DataSourceAttributes() map[string]dataSourceSchema.Attribute {
 	return map[string]dataSourceSchema.Attribute{
 		"id": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Interface Map ID.  Required when the Interface Map name is omitted.",
+			MarkdownDescription: "Apstra Interface Map ID. Required when `name` is omitted.",
 			Optional:            true,
 			Computed:            true,
 			Validators: []validator.String{
@@ -34,7 +34,7 @@ func (o InterfaceMap) DataSourceAttributes() map[string]dataSourceSchema.Attribu
 			},
 		},
 		"name": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Interface Map name displayed in the Apstra web UI.  Required when Interface Map ID is omitted.",
+			MarkdownDescription: "Interface Map name displayed in the Apstra web UI. Required when `id` is omitted.",
 			Optional:            true,
 			Computed:            true,
 			Validators:          []validator.String{stringvalidator.LengthAtLeast(1)},

diff --git a/apstra/design/logical_device.go b/apstra/design/logical_device.go
@@ -26,7 +26,7 @@ type LogicalDevice struct {
 func (o LogicalDevice) DataSourceAttributes() map[string]dataSourceSchema.Attribute {
 	return map[string]dataSourceSchema.Attribute{
 		"id": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Populate this field to look up a Logical Device by ID. Required when `name`is omitted.",
+			MarkdownDescription: "Apstra ID of the Logical Device. Required when `name` is omitted.",
 			Optional:            true,
 			Computed:            true,
 			Validators: []validator.String{
@@ -38,7 +38,7 @@ func (o LogicalDevice) DataSourceAttributes() map[string]dataSourceSchema.Attrib
 			},
 		},
 		"name": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Populate this field to look up a Logical Device by name. Required when `id`is omitted.",
+			MarkdownDescription: "Web UI name of the Logical Device. Required when `id` is omitted.",
 			Optional:            true,
 			Computed:            true,
 			Validators:          []validator.String{stringvalidator.LengthAtLeast(1)},

diff --git a/apstra/design/property_set.go b/apstra/design/property_set.go
@@ -27,7 +27,7 @@ type PropertySet struct {
 func (o PropertySet) DataSourceAttributes() map[string]dataSourceSchema.Attribute {
 	return map[string]dataSourceSchema.Attribute{
 		"id": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Populate this field to look up a Property Set by ID. Required when `name` is omitted.",
+			MarkdownDescription: "Apstra ID of the Property Set. Required when `name` is omitted.",
 			Optional:            true,
 			Computed:            true,
 			Validators: []validator.String{
@@ -39,7 +39,7 @@ func (o PropertySet) DataSourceAttributes() map[string]dataSourceSchema.Attribut
 			},
 		},
 		"name": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Populate this field to look up a Property Set by name. Required when `id` is omitted.",
+			MarkdownDescription: "Web UID name of the Property Set. Required when `id` is omitted.",
 			Optional:            true,
 			Computed:            true,
 			Validators:          []validator.String{stringvalidator.LengthAtLeast(1)},

diff --git a/apstra/design/rack_type.go b/apstra/design/rack_type.go
@@ -32,7 +32,7 @@ type RackType struct {
 func (o RackType) DataSourceAttributes() map[string]dataSourceSchema.Attribute {
 	return map[string]dataSourceSchema.Attribute{
 		"id": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Rack Type ID.  Required when the Rack Type name is omitted.",
+			MarkdownDescription: "Apstra ID of the Rack Type. Required when `name` is omitted.",
 			Optional:            true,
 			Computed:            true,
 			Validators: []validator.String{
@@ -44,7 +44,7 @@ func (o RackType) DataSourceAttributes() map[string]dataSourceSchema.Attribute {
 			},
 		},
 		"name": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Rack Type name displayed in the Apstra web UI.  Required when Rack Type ID is omitted.",
+			MarkdownDescription: "Web UI name of the Type. Required when `id` is omitted.",
 			Optional:            true,
 			Computed:            true,
 			Validators:          []validator.String{stringvalidator.LengthAtLeast(1)},

diff --git a/apstra/design/tag.go b/apstra/design/tag.go
@@ -25,7 +25,7 @@ type Tag struct {
 func (o Tag) DataSourceAttributes() map[string]dataSourceSchema.Attribute {
 	return map[string]dataSourceSchema.Attribute{
 		"id": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Populate this field to look up a Tag by ID. Required when `name`is omitted.",
+			MarkdownDescription: "Apstra ID of the Tag. Required when `name` is omitted.",
 			Optional:            true,
 			Computed:            true,
 			Validators: []validator.String{
@@ -37,7 +37,7 @@ func (o Tag) DataSourceAttributes() map[string]dataSourceSchema.Attribute {
 			},
 		},
 		"name": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Populate this field to look up a Tag by name. Required when `id` is omitted.",
+			MarkdownDescription: "Web UI name of the Tag. Required when `id` is omitted.",
 			Optional:            true,
 			Computed:            true,
 			Validators: []validator.String{

diff --git a/apstra/design/template_rack_based.go b/apstra/design/template_rack_based.go
@@ -33,7 +33,7 @@ type TemplateRackBased struct {
 func (o TemplateRackBased) DataSourceAttributes() map[string]dataSourceSchema.Attribute {
 	return map[string]dataSourceSchema.Attribute{
 		"id": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Template ID.  Required when the Template name is omitted.",
+			MarkdownDescription: "Apstra Template ID. Required when `id` is omitted.",
 			Optional:            true,
 			Computed:            true,
 			Validators: []validator.String{
@@ -45,7 +45,7 @@ func (o TemplateRackBased) DataSourceAttributes() map[string]dataSourceSchema.At
 			},
 		},
 		"name": dataSourceSchema.StringAttribute{
-			MarkdownDescription: "Template name displayed in the Apstra web UI.  Required when Template ID is omitted.",
+			MarkdownDescription: "Web UI name of the Template. Required when `id` is omitted.",
 			Optional:            true,
 			Computed:            true,
 			Validators: []validator.String{