From 9f6563e4575720c2a04b63554b92fd856a092ce9 Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Thu, 22 Sep 2022 15:05:55 -0400 Subject: [PATCH] add reasons, table Signed-off-by: Todd Baert --- specification.json | 2 +- specification/sections/02-providers.md | 4 ++-- specification/types.md | 11 +++++++++++ 3 files changed, 14 insertions(+), 3 deletions(-) diff --git a/specification.json b/specification.json index 0f6f168a..d535e1d1 100644 --- a/specification.json +++ b/specification.json @@ -223,7 +223,7 @@ { "id": "Requirement 2.6", "machine_id": "requirement_2_6", - "content": "The `provider` SHOULD populate the `flag resolution` structure's `reason` field with a string indicating the semantic reason for the returned flag value.", + "content": "The `provider` SHOULD populate the `flag resolution` structure's `reason` field with `\"DEFAULT\",` `\"TARGETING_MATCH\"`, `\"SPLIT\"`, `\"DISABLED\"`, `\"UNKNOWN\"`, `\"ERROR\"` or some other string indicating the semantic reason for the returned flag value.", "RFC 2119 keyword": "SHOULD", "children": [] }, diff --git a/specification/sections/02-providers.md b/specification/sections/02-providers.md index f24e2278..64cdbc8b 100644 --- a/specification/sections/02-providers.md +++ b/specification/sections/02-providers.md @@ -75,9 +75,9 @@ The value of the variant field might only be meaningful in the context of the fl ##### Requirement 2.6 -> The `provider` **SHOULD** populate the `flag resolution` structure's `reason` field with a string indicating the semantic reason for the returned flag value. +> The `provider` **SHOULD** populate the `flag resolution` structure's `reason` field with `"DEFAULT",` `"TARGETING_MATCH"`, `"SPLIT"`, `"DISABLED"`, `"UNKNOWN"`, `"ERROR"` or some other string indicating the semantic reason for the returned flag value. -Possible values vary by provider, but might include such values as `"TARGETING_MATCH"`, `"SPLIT"`, `"DISABLED"`, `"DEFAULT"`, `"UNKNOWN"` or `"ERROR"`. +As indicated in the definition of the [`flag resolution`](../types.md#resolution-details) structure, the `reason` should be a string. This allows providers to reflect accurately why a flag was resolved to a particular value. ##### Requirement 2.7 diff --git a/specification/types.md b/specification/types.md index a2bd15e6..1fc89c06 100644 --- a/specification/types.md +++ b/specification/types.md @@ -49,6 +49,17 @@ A structure which contains a subset of the fields defined in the `evaluation det - reason (string, optional) - variant (string, optional) +A set of pre-defined reasons is enumerated below: + +| Reason | Explanation | +| --------------- | ----------------------------------------------------------------------------------------------------- | +| DEFAULT | The resolved value was configured statically, or otherwise fell back to a pre-configured value. | +| TARGETING_MATCH | The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting. | +| SPLIT | The resolved value was the result of pseudorandom assignment. | +| DISABLED | The resolved value was the result of the flag being disabled in the management system. | +| UNKNOWN | The reason for the resolved value could not be determined. | +| ERROR | The resolved value was the result of an error. | + > NOTE: The `resolution details` structure is not exposed to the Application Author. It defines the data which Provider Authors must return when resolving the value of flags. ### Evaluation Options