OFEP-007: Surfacing flag metadata

specification.json

@@ -138,41 +138,63 @@
         {
             "id": "Requirement 1.4.7",
             "machine_id": "requirement_1_4_7",
+            "content": "If the `flag metadata` field in the `flag resolution` structure returned by the configured `provider` is set, the `evaluation details` structure's `flag metadata` field MUST contain that value. Otherwise, it MUST contain an empty record.",
+            "RFC 2119 keyword": "MUST",
+            "children": []
+        },
+        {
+            "id": "Condition 1.4.8",
+            "machine_id": "condition_1_4_8",
+            "content": "The implementation language supports a mechanism for marking data as immutable.",
+            "RFC 2119 keyword": null,
+            "children": [
+                {
+                    "id": "Conditional Requirement 1.4.8.1",
+                    "machine_id": "conditional_requirement_1_4_8_1",
+                    "content": "Condition: `Flag metadata` MUST be immutable.",
+                    "RFC 2119 keyword": "MUST",
+                    "children": []
+                }
+            ]
+        },
+        {
+            "id": "Requirement 1.4.9",
+            "machine_id": "requirement_1_4_9",
             "content": "In cases of abnormal execution, the `evaluation details` structure's `error code` field MUST contain an `error code`.",
             "RFC 2119 keyword": "MUST",
             "children": []
         },
         {
-            "id": "Requirement 1.4.8",
-            "machine_id": "requirement_1_4_8",
+            "id": "Requirement 1.4.10",
+            "machine_id": "requirement_1_4_10",
             "content": "In cases of abnormal execution (network failure, unhandled error, etc) the `reason` field in the `evaluation details` SHOULD indicate an error.",
             "RFC 2119 keyword": "SHOULD",
             "children": []
         },
         {
-            "id": "Requirement 1.4.9",
-            "machine_id": "requirement_1_4_9",
+            "id": "Requirement 1.4.11",
+            "machine_id": "requirement_1_4_11",
             "content": "Methods, functions, or operations on the client MUST NOT throw exceptions, or otherwise abnormally terminate. Flag evaluation calls must always return the `default value` in the event of abnormal execution. Exceptions include functions or methods for the purposes for configuration or setup.",
             "RFC 2119 keyword": "MUST NOT",
             "children": []
         },
         {
-            "id": "Requirement 1.4.10",
-            "machine_id": "requirement_1_4_10",
+            "id": "Requirement 1.4.12",
+            "machine_id": "requirement_1_4_12",
             "content": "In the case of abnormal execution, the client SHOULD log an informative error message.",
             "RFC 2119 keyword": "SHOULD",
             "children": []
         },
         {
-            "id": "Requirement 1.4.11",
-            "machine_id": "requirement_1_4_11",
+            "id": "Requirement 1.4.13",
+            "machine_id": "requirement_1_4_13",
             "content": "The `client` SHOULD provide asynchronous or non-blocking mechanisms for flag evaluation.",
             "RFC 2119 keyword": "SHOULD",
             "children": []
         },
         {
-            "id": "Requirement 1.4.12",
-            "machine_id": "requirement_1_4_12",
+            "id": "Requirement 1.4.14",
+            "machine_id": "requirement_1_4_14",
             "content": "In cases of abnormal execution, the `evaluation details` structure's `error message` field MAY contain a string containing additional details about the nature of the error.",
             "RFC 2119 keyword": "MAY",
             "children": []
@@ -237,26 +259,33 @@
         {
             "id": "Requirement 2.2.6",
             "machine_id": "requirement_2_2_6",
-            "content": "In cases of normal execution, the `provider` MUST NOT populate the `resolution details` structure's `error code` field, or otherwise must populate it with a null or falsy value.",
-            "RFC 2119 keyword": "MUST NOT",
+            "content": "The `provider` SHOULD populate the `resolution details` structure's `flag metadata` field.  `flag metadata` MUST be a structure supports definition of arbitrary properties, with keys of type `string`, and values of type `boolean | string | number`.",
+            "RFC 2119 keyword": "MUST",
             "children": []
         },
         {
             "id": "Requirement 2.2.7",
             "machine_id": "requirement_2_2_7",
+            "content": "In cases of normal execution, the `provider` MUST NOT populate the `resolution details` structure's `error code` field, or otherwise must populate it with a null or falsy value.",
+            "RFC 2119 keyword": "MUST NOT",
+            "children": []
+        },
+        {
+            "id": "Requirement 2.2.8",
+            "machine_id": "requirement_2_2_8",
             "content": "In cases of abnormal execution, the `provider` MUST indicate an error using the idioms of the implementation language, with an associated `error code` and optional associated `error message`.",
             "RFC 2119 keyword": "MUST",
             "children": []
         },
         {
-            "id": "Condition 2.2.8",
-            "machine_id": "condition_2_2_8",
+            "id": "Condition 2.2.9",
+            "machine_id": "condition_2_2_9",
             "content": "The implementation language supports generics (or an equivalent feature).",
             "RFC 2119 keyword": null,
             "children": [
                 {
-                    "id": "Conditional Requirement 2.2.8.1",
-                    "machine_id": "conditional_requirement_2_2_8_1",
+                    "id": "Conditional Requirement 2.2.9.1",
+                    "machine_id": "conditional_requirement_2_2_9_1",
                     "content": "The `resolution details` structure SHOULD accept a generic argument (or use an equivalent language feature) which indicates the type of the wrapped `value` field.",
                     "RFC 2119 keyword": "SHOULD",
                     "children": []

specification/sections/01-flag-evaluation.md

@@ -189,33 +189,45 @@ FlagEvaluationDetails<MyStruct> myStructDetails = client.getObjectDetails<MyStru
 
 ##### Requirement 1.4.7
 
+> If the `flag metadata` field in the `flag resolution` structure returned by the configured `provider` is set, the `evaluation details` structure's `flag metadata` field **MUST** contain that value. Otherwise, it **MUST** contain an empty record.
+
+##### Condition 1.4.8
+
+> The implementation language supports a mechanism for marking data as immutable.
+
+###### Conditional Requirement 1.4.8.1
+
+> Condition: `Flag metadata` **MUST** be immutable.
+
+##### Requirement 1.4.9
+
 > In cases of abnormal execution, the `evaluation details` structure's `error code` field **MUST** contain an `error code`.
 
 See [error code](../types.md#error-code) for details.
 
-##### Requirement 1.4.8
+##### Requirement 1.4.10
 
 > In cases of abnormal execution (network failure, unhandled error, etc) the `reason` field in the `evaluation details` **SHOULD** indicate an error.
 
-##### Requirement 1.4.9
+##### Requirement 1.4.11
 
 > Methods, functions, or operations on the client **MUST NOT** throw exceptions, or otherwise abnormally terminate. Flag evaluation calls must always return the `default value` in the event of abnormal execution. Exceptions include functions or methods for the purposes for configuration or setup.
 
 Configuration code includes code to set the provider, instantiate providers, and configure the global API object.
 
-##### Requirement 1.4.10
+##### Requirement 1.4.12
 
 > In the case of abnormal execution, the client **SHOULD** log an informative error message.
 
 Implementations may define a standard logging interface that can be supplied as an optional argument to the client creation function, which may wrap standard logging functionality of the implementation language.
 
-##### Requirement 1.4.11
+##### Requirement 1.4.13
 
 > The `client` **SHOULD** provide asynchronous or non-blocking mechanisms for flag evaluation.
 
 It's recommended to provide non-blocking mechanisms for flag evaluation, particularly in languages or environments wherein there's a single thread of execution.
 
-##### Requirement 1.4.12
+##### Requirement 1.4.14
 
 > In cases of abnormal execution, the `evaluation details` structure's `error message` field **MAY** contain a string containing additional details about the nature of the error.
 

specification/sections/02-providers.md

@@ -83,10 +83,16 @@ As indicated in the definition of the [`resolution details`](../types.md#resolut
 
 ##### Requirement 2.2.6
 
-> In cases of normal execution, the `provider` **MUST NOT** populate the `resolution details` structure's `error code` field, or otherwise must populate it with a null or falsy value.
+> The `provider` **SHOULD** populate the `resolution details` structure's `flag metadata` field. 
+
+> `flag metadata` **MUST** be a structure supports definition of arbitrary properties, with keys of type `string`, and values of type `boolean | string | number`.
 
 ##### Requirement 2.2.7
 
+> In cases of normal execution, the `provider` **MUST NOT** populate the `resolution details` structure's `error code` field, or otherwise must populate it with a null or falsy value.
+
+##### Requirement 2.2.8
+
 > In cases of abnormal execution, the `provider` **MUST** indicate an error using the idioms of the implementation language, with an associated `error code` and optional associated `error message`.
 
 The provider might throw an exception, return an error, or populate the `error code` object on the returned `resolution details` structure to indicate a problem during flag value resolution.
@@ -98,11 +104,11 @@ See [error code](../types.md#error-code) for details.
 throw new ProviderError(ErrorCode.INVALID_CONTEXT, "The 'foo' attribute must be a string.");
 ```
 
-##### Condition 2.2.8
+##### Condition 2.2.9
 
 > The implementation language supports generics (or an equivalent feature).
 
-###### Conditional Requirement 2.2.8.1
+###### Conditional Requirement 2.2.9.1
 
 > The `resolution details` structure **SHOULD** accept a generic argument (or use an equivalent language feature) which indicates the type of the wrapped `value` field.
 

specification/types.md

@@ -40,6 +40,7 @@ A structure representing the result of the [flag evaluation process](./glossary.
 - error message (string, optional)
 - reason (string, optional)
 - variant (string, optional)
+- flag metadata (Record<string,boolean | string | number>)
 
 ### Resolution Details
 
@@ -50,6 +51,7 @@ A structure which contains a subset of the fields defined in the `evaluation det
 - error message (string, optional)
 - reason (string, optional)
 - variant (string, optional)
+- flag metadata (Record<string,boolean | string | number>, optional)
 
 A set of pre-defined reasons is enumerated below: