Clarify allocation ID and allocation key descriptions in feature flag specs

.generator/schemas/v2/openapi.yaml

@@ -7356,12 +7356,12 @@ components:
             $ref: "#/components/schemas/GuardrailMetric"
           type: array
         id:
-          description: The unique identifier of the targeting rule allocation.
+          description: "The unique identifier of the targeting rule allocation. Use this ID with the allocation management endpoints, such as `/api/v2/allocations/{allocation_id}`. It is not included in SDK evaluation results or exposure events."
           example: "550e8400-e29b-41d4-a716-446655440020"
           format: uuid
           type: string
         key:
-          description: The unique key of the targeting rule allocation.
+          description: "The unique key of the targeting rule allocation. SDKs report this key in flag evaluation results and exposure events to indicate which targeting rule assigned the variant. Use it to match evaluation or experiment data to this rule."
           example: "prod-rollout"
           type: string
         name:
@@ -7419,7 +7419,7 @@ components:
         attributes:
           $ref: "#/components/schemas/Allocation"
         id:
-          description: The unique identifier of the targeting rule allocation.
+          description: "The unique identifier of the targeting rule allocation. Use this ID with the allocation management endpoints, such as `/api/v2/allocations/{allocation_id}`. It is not included in SDK evaluation results or exposure events."
           example: "550e8400-e29b-41d4-a716-446655440020"
           format: uuid
           type: string
@@ -7554,7 +7554,7 @@ components:
           nullable: true
           type: string
         allocation_id:
-          description: The targeting rule allocation ID this progressive rollout belongs to.
+          description: "The unique identifier (UUID) of the targeting rule allocation this progressive rollout belongs to. This is not the allocation key that SDKs report in evaluation results and exposure events."
           example: "550e8400-e29b-41d4-a716-446655440020"
           format: uuid
           type: string
@@ -48004,7 +48004,7 @@ components:
       nullable: true
       properties:
         allocation_key:
-          description: "Key of the feature flag allocation linked to the experiment."
+          description: "Key of the feature flag allocation linked to the experiment. Matches the allocation key that SDKs report in flag evaluation results and exposure events."
           type: string
         entry_point:
           $ref: >-
@@ -51236,7 +51236,7 @@ components:
           nullable: true
           type: object
         default_allocation_key:
-          description: The allocation key used for the default variant.
+          description: "A system-generated allocation key, in the format `allocation-default-<hash>`, that SDKs report in flag evaluation results and exposure events when a subject receives the environment's default variant because no targeting rule matched. It has no corresponding allocation ID and cannot be used with the allocation endpoints."
           example: "allocation-default-123abc"
           type: string
         default_variant_id:
@@ -51272,7 +51272,7 @@ components:
           example: false
           type: boolean
         override_allocation_key:
-          description: The allocation key used for the override variant.
+          description: "A system-generated allocation key, in the format `allocation-override-<hash>`, that SDKs report in flag evaluation results and exposure events when the environment's override variant is served. It has no corresponding allocation ID and cannot be used with the allocation endpoints."
           example: "allocation-override-123abc"
           type: string
         override_variant_id:
@@ -51299,7 +51299,7 @@ components:
       description: Environment-specific settings for a feature flag in list responses.
       properties:
         default_allocation_key:
-          description: The allocation key used for the default variant.
+          description: "A system-generated allocation key, in the format `allocation-default-<hash>`, that SDKs report in flag evaluation results and exposure events when a subject receives the environment's default variant because no targeting rule matched. It has no corresponding allocation ID and cannot be used with the allocation endpoints."
           example: "allocation-default-123abc"
           type: string
         default_variant_id:
@@ -51335,7 +51335,7 @@ components:
           example: false
           type: boolean
         override_allocation_key:
-          description: The allocation key used for the override variant.
+          description: "A system-generated allocation key, in the format `allocation-override-<hash>`, that SDKs report in flag evaluation results and exposure events when the environment's override variant is served. It has no corresponding allocation ID and cannot be used with the allocation endpoints."
           example: "allocation-override-123abc"
           type: string
         override_variant_id:
@@ -142291,12 +142291,12 @@ components:
             $ref: "#/components/schemas/GuardrailMetricRequest"
           type: array
         id:
-          description: The unique identifier of the targeting rule allocation.
+          description: "The unique identifier of the targeting rule allocation. Use this ID with the allocation management endpoints, such as `/api/v2/allocations/{allocation_id}`. It is not included in SDK evaluation results or exposure events."
           example: "550e8400-e29b-41d4-a716-446655440020"
           format: uuid
           type: string
         key:
-          description: The unique key of the targeting rule allocation.
+          description: "The unique key of the targeting rule allocation. SDKs report this key in flag evaluation results and exposure events to indicate which targeting rule assigned the variant. Use it to match evaluation or experiment data to this rule."
           example: "prod-rollout"
           type: string
         name:

src/main/java/com/datadog/api/client/v2/model/Allocation.java

@@ -262,7 +262,9 @@ public Allocation id(UUID id) {
   }
 
   /**
-   * The unique identifier of the targeting rule allocation.
+   * The unique identifier of the targeting rule allocation. Use this ID with the allocation
+   * management endpoints, such as <code>/api/v2/allocations/{allocation_id}</code>. It is not
+   * included in SDK evaluation results or exposure events.
    *
    * @return id
    */
@@ -283,7 +285,9 @@ public Allocation key(String key) {
   }
 
   /**
-   * The unique key of the targeting rule allocation.
+   * The unique key of the targeting rule allocation. SDKs report this key in flag evaluation
+   * results and exposure events to indicate which targeting rule assigned the variant. Use it to
+   * match evaluation or experiment data to this rule.
    *
    * @return key
    */

src/main/java/com/datadog/api/client/v2/model/AllocationDataResponse.java

@@ -81,7 +81,9 @@ public AllocationDataResponse id(UUID id) {
   }
 
   /**
-   * The unique identifier of the targeting rule allocation.
+   * The unique identifier of the targeting rule allocation. Use this ID with the allocation
+   * management endpoints, such as <code>/api/v2/allocations/{allocation_id}</code>. It is not
+   * included in SDK evaluation results or exposure events.
    *
    * @return id
    */

src/main/java/com/datadog/api/client/v2/model/AllocationExposureSchedule.java

@@ -135,7 +135,8 @@ public AllocationExposureSchedule allocationId(UUID allocationId) {
   }
 
   /**
-   * The targeting rule allocation ID this progressive rollout belongs to.
+   * The unique identifier (UUID) of the targeting rule allocation this progressive rollout belongs
+   * to. This is not the allocation key that SDKs report in evaluation results and exposure events.
    *
    * @return allocationId
    */

src/main/java/com/datadog/api/client/v2/model/ExperimentsPatchExperimentV2ResponseDataAttributesDatadogFlagConfiguration.java

@@ -72,7 +72,8 @@ public ExperimentsPatchExperimentV2ResponseDataAttributesDatadogFlagConfiguratio
   }
 
   /**
-   * Key of the feature flag allocation linked to the experiment.
+   * Key of the feature flag allocation linked to the experiment. Matches the allocation key that
+   * SDKs report in flag evaluation results and exposure events.
    *
    * @return allocationKey
    */

src/main/java/com/datadog/api/client/v2/model/FeatureFlagEnvironment.java

@@ -143,7 +143,10 @@ public FeatureFlagEnvironment defaultAllocationKey(String defaultAllocationKey)
   }
 
   /**
-   * The allocation key used for the default variant.
+   * A system-generated allocation key, in the format <code>allocation-default-&lt;hash&gt;</code>,
+   * that SDKs report in flag evaluation results and exposure events when a subject receives the
+   * environment's default variant because no targeting rule matched. It has no corresponding
+   * allocation ID and cannot be used with the allocation endpoints.
    *
    * @return defaultAllocationKey
    */
@@ -308,7 +311,10 @@ public FeatureFlagEnvironment overrideAllocationKey(String overrideAllocationKey
   }
 
   /**
-   * The allocation key used for the override variant.
+   * A system-generated allocation key, in the format <code>allocation-override-&lt;hash&gt;</code>,
+   * that SDKs report in flag evaluation results and exposure events when the environment's override
+   * variant is served. It has no corresponding allocation ID and cannot be used with the allocation
+   * endpoints.
    *
    * @return overrideAllocationKey
    */

src/main/java/com/datadog/api/client/v2/model/FeatureFlagEnvironmentListItem.java

@@ -95,7 +95,10 @@ public FeatureFlagEnvironmentListItem defaultAllocationKey(String defaultAllocat
   }
 
   /**
-   * The allocation key used for the default variant.
+   * A system-generated allocation key, in the format <code>allocation-default-&lt;hash&gt;</code>,
+   * that SDKs report in flag evaluation results and exposure events when a subject receives the
+   * environment's default variant because no targeting rule matched. It has no corresponding
+   * allocation ID and cannot be used with the allocation endpoints.
    *
    * @return defaultAllocationKey
    */
@@ -261,7 +264,10 @@ public FeatureFlagEnvironmentListItem overrideAllocationKey(String overrideAlloc
   }
 
   /**
-   * The allocation key used for the override variant.
+   * A system-generated allocation key, in the format <code>allocation-override-&lt;hash&gt;</code>,
+   * that SDKs report in flag evaluation results and exposure events when the environment's override
+   * variant is served. It has no corresponding allocation ID and cannot be used with the allocation
+   * endpoints.
    *
    * @return overrideAllocationKey
    */

src/main/java/com/datadog/api/client/v2/model/UpsertAllocationRequest.java

@@ -180,7 +180,9 @@ public UpsertAllocationRequest id(UUID id) {
   }
 
   /**
-   * The unique identifier of the targeting rule allocation.
+   * The unique identifier of the targeting rule allocation. Use this ID with the allocation
+   * management endpoints, such as <code>/api/v2/allocations/{allocation_id}</code>. It is not
+   * included in SDK evaluation results or exposure events.
    *
    * @return id
    */
@@ -201,7 +203,9 @@ public UpsertAllocationRequest key(String key) {
   }
 
   /**
-   * The unique key of the targeting rule allocation.
+   * The unique key of the targeting rule allocation. SDKs report this key in flag evaluation
+   * results and exposure events to indicate which targeting rule assigned the variant. Use it to
+   * match evaluation or experiment data to this rule.
    *
    * @return key
    */