From f1295f24b7432daa981989a9a9357ce35a1b252a Mon Sep 17 00:00:00 2001 From: bradcypert Date: Thu, 15 Jan 2026 17:04:46 -0500 Subject: [PATCH 1/2] docs(terraform): Add information on only-send-changed-attributes --- docs/terraform/customize/entity-mapping.mdx | 57 +++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/docs/terraform/customize/entity-mapping.mdx b/docs/terraform/customize/entity-mapping.mdx index 0673ec0f..3a91bff9 100644 --- a/docs/terraform/customize/entity-mapping.mdx +++ b/docs/terraform/customize/entity-mapping.mdx @@ -321,6 +321,63 @@ In this example: The `WaitForCompleted` polling method for the API operation defaults to a 5 second interval, however the create entity operation overrides to a 10 second interval. +### Only-Send-Changed-Attributes + +Define automatic patch semantics for Terraform provider update operations via the `x-speakeasy-entity-operation` extension in the OpenAPI Specification document. When enabled, update operations will only send attributes that have changed from their prior state, rather than sending the entire resource representation. + +This is particularly useful for APIs that support partial updates (PATCH semantics) where sending unchanged fields may cause unintended side effects or where bandwidth efficiency is important. + +#### Basic Usage + +In this example: + +```yaml +/resource: + post: + x-speakeasy-entity-operation: + - entityOperation: Resource#create,update + options: + patch: + style: only-send-changed-attributes + operationId: create-or-update-resource + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceRequest' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceResponse' +``` + +The `create,update` entity operation uses the `only-send-changed-attributes` patch style. During update operations, the generated Terraform provider will compare each attribute against its prior state and only include attributes that have changed in the API request. + +#### Configuration + +The patch style is configured within the `options` section of an entity operation mapping: + +```yaml +x-speakeasy-entity-operation: + - entityOperation: Entity#operation + options: + patch: + style: only-send-changed-attributes +``` + +#### When to Use + +Use `only-send-changed-attributes` when: + +- Your API supports partial updates (PATCH semantics) and may have side effects when unchanged fields are sent +- You want to minimize request payload size by excluding unchanged attributes +- Your API has fields where re-sending the same value triggers unwanted behavior (such as regenerating tokens or timestamps) + + ### Manual association between Operations and Resource / Data Sources The default behavior within Speakeasy is to automatically infer a data source from all operations that have an `x-speakeasy-entity-operation: Entity#read` association defined. From 5d26d519e66a2f79a3ca6816dac6bbc1329dc64b Mon Sep 17 00:00:00 2001 From: Brad Date: Fri, 16 Jan 2026 12:52:07 -0500 Subject: [PATCH 2/2] Refactor entity mapping documentation for clarity Updated section headers and descriptions for clarity regarding entity operations and patch semantics. --- docs/terraform/customize/entity-mapping.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/terraform/customize/entity-mapping.mdx b/docs/terraform/customize/entity-mapping.mdx index 3a91bff9..72fbdd74 100644 --- a/docs/terraform/customize/entity-mapping.mdx +++ b/docs/terraform/customize/entity-mapping.mdx @@ -321,11 +321,11 @@ In this example: The `WaitForCompleted` polling method for the API operation defaults to a 5 second interval, however the create entity operation overrides to a 10 second interval. -### Only-Send-Changed-Attributes +### Update Patch Semantics -Define automatic patch semantics for Terraform provider update operations via the `x-speakeasy-entity-operation` extension in the OpenAPI Specification document. When enabled, update operations will only send attributes that have changed from their prior state, rather than sending the entire resource representation. +Define automatic patch semantics for Terraform provider update operations via the `x-speakeasy-entity-operation` extension in the OpenAPI Specification document. When enabled, entity operations will only send attributes that have changed from their prior state, rather than sending the entire resource representation. -This is particularly useful for APIs that support partial updates (PATCH semantics) where sending unchanged fields may cause unintended side effects or where bandwidth efficiency is important. +This is particularly useful for APIs that support partial updates (such as PATCH semantics) where sending unchanged fields may cause unintended side effects or where bandwidth efficiency is important. #### Basic Usage @@ -355,7 +355,7 @@ In this example: $ref: '#/components/schemas/ResourceResponse' ``` -The `create,update` entity operation uses the `only-send-changed-attributes` patch style. During update operations, the generated Terraform provider will compare each attribute against its prior state and only include attributes that have changed in the API request. +The `create,update` entity operation uses the `only-send-changed-attributes` patch style. During entity operations, the generated Terraform provider will compare each attribute against its prior state and only include attributes that have changed in the API request. #### Configuration