diff --git a/docs/images/block-type-inspect-ref-key.png b/docs/images/block-type-inspect-ref-key.png
new file mode 100644
index 00000000..e0202c23
Binary files /dev/null and b/docs/images/block-type-inspect-ref-key.png differ
diff --git a/docs/resources/block.md b/docs/resources/block.md
index 6427bffc..39f3f3bf 100644
--- a/docs/resources/block.md
+++ b/docs/resources/block.md
@@ -70,8 +70,42 @@ resource "prefect_block" "gcp_credentials_key" {
"service_account_info" = jsondecode(base64decode(google_service_account_key.test_bot.private_key))
})
}
+
+# example:
+# some resources need to be referenced using a "$ref" key
+resource "prefect_block" "my_dbt_cli_profile" {
+ name = "my-dbt-cli-profile"
+ type_slug = "dbt-cli-profile"
+
+ data = jsonencode({
+ "name" = "mine"
+ "target" = "prefect-dbt-profile"
+ })
+}
+resource "prefect_block" "my_dbt_run_operation_block" {
+ name = "my-dbt-operations"
+ type_slug = "dbt-core-operation"
+
+ # note the "$ref" key wrapping the "block_document_id" reference
+ data = jsonencode({
+ "commands" = ["dbt deps", "dbt seed", "dbt run"]
+ "dbt_cli_profile" = { "$ref" : { "block_document_id" : prefect_block.my_dbt_cli_profile.id } }
+ })
+}
```
+One of the examples above mentions the special syntax needed when referencing
+other Terraform resources from within the `data` attribute. You can use `prefect
+block type inspect` to confirm when this field is required.
+
+For example, the following screenshot shows the output of `prefect block type inspect
+dbt-core-operation`. It mentions the `$ref` key that the API expects.
+
+
+
+For more information on the `$ref` syntax definition, see the
+[dollarref's specification in the JSON schema](https://json-schema.org/understanding-json-schema/structuring#dollarref).
+
## Schema
diff --git a/examples/resources/prefect_block/resource.tf b/examples/resources/prefect_block/resource.tf
index f1675a65..ec37a4b9 100644
--- a/examples/resources/prefect_block/resource.tf
+++ b/examples/resources/prefect_block/resource.tf
@@ -47,3 +47,25 @@ resource "prefect_block" "gcp_credentials_key" {
"service_account_info" = jsondecode(base64decode(google_service_account_key.test_bot.private_key))
})
}
+
+# example:
+# some resources need to be referenced using a "$ref" key
+resource "prefect_block" "my_dbt_cli_profile" {
+ name = "my-dbt-cli-profile"
+ type_slug = "dbt-cli-profile"
+
+ data = jsonencode({
+ "name" = "mine"
+ "target" = "prefect-dbt-profile"
+ })
+}
+resource "prefect_block" "my_dbt_run_operation_block" {
+ name = "my-dbt-operations"
+ type_slug = "dbt-core-operation"
+
+ # note the "$ref" key wrapping the "block_document_id" reference
+ data = jsonencode({
+ "commands" = ["dbt deps", "dbt seed", "dbt run"]
+ "dbt_cli_profile" = { "$ref" : { "block_document_id" : prefect_block.my_dbt_cli_profile.id } }
+ })
+}
diff --git a/internal/provider/resources/block.go b/internal/provider/resources/block.go
index 7a4b313a..51add2da 100644
--- a/internal/provider/resources/block.go
+++ b/internal/provider/resources/block.go
@@ -418,13 +418,13 @@ func (r *BlockResource) Update(ctx context.Context, req resource.UpdateRequest,
return
}
- byteSlice, err := json.Marshal(block.Data)
- if err != nil {
- resp.Diagnostics.Append(helpers.SerializeDataErrorDiagnostic("data", "Block Data", err))
-
- return
- }
- plan.Data = jsontypes.NewNormalizedValue(string(byteSlice))
+ // Normally, we would also copy the retrieved Block's Data field into the
+ // plan object before setting the current state.
+ //
+ // However, the API's GET method does not return the `$ref` expression if it
+ // was specified in the Data field on the Block resource. This leads to
+ // "inconsistent result after apply" errors. For now, we'll skip copying the
+ // retrieved Block's Data field and use what was specified in the plan.
diags = resp.State.Set(ctx, &plan)
resp.Diagnostics.Append(diags...)
diff --git a/templates/images/block-type-inspect-ref-key.png b/templates/images/block-type-inspect-ref-key.png
new file mode 100644
index 00000000..e0202c23
Binary files /dev/null and b/templates/images/block-type-inspect-ref-key.png differ
diff --git a/templates/resources/block.md.tmpl b/templates/resources/block.md.tmpl
new file mode 100644
index 00000000..abc79ef3
--- /dev/null
+++ b/templates/resources/block.md.tmpl
@@ -0,0 +1,35 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}"
+subcategory: ""
+description: |-
+{{ .Description | plainmarkdown | trimspace | prefixlines " " }}
+---
+
+# {{.Name}} ({{.Type}})
+
+{{.Description}}
+
+## Example Usage
+
+{{tffile .ExampleFile}}
+
+One of the examples above mentions the special syntax needed when referencing
+other Terraform resources from within the `data` attribute. You can use `prefect
+block type inspect` to confirm when this field is required.
+
+For example, the following screenshot shows the output of `prefect block type inspect
+dbt-core-operation`. It mentions the `$ref` key that the API expects.
+
+
+
+For more information on the `$ref` syntax definition, see the
+[dollarref's specification in the JSON schema](https://json-schema.org/understanding-json-schema/structuring#dollarref).
+
+{{.SchemaMarkdown | trimspace}}
+
+## Import
+
+Import is supported using the following syntax:
+
+{{codefile "shell" .ImportFile}}