add reasons, table

Signed-off-by: Todd Baert <[email protected]>

Author: toddbaert

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": []
         },

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
 

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