OFEP-007: Surfacing flag metadata

specification.json

@@ -177,6 +177,28 @@
             "RFC 2119 keyword": "MAY",
             "children": []
         },
+        {
+            "id": "Requirement 1.4.13",
+            "machine_id": "requirement_1_4_13",
+            "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.14",
+            "machine_id": "condition_1_4_14",
+            "content": "The implementation language supports a mechanism for marking data as immutable.",
+            "RFC 2119 keyword": null,
+            "children": [
+                {
+                    "id": "Conditional Requirement 1.4.14.1",
+                    "machine_id": "conditional_requirement_1_4_14_1",
+                    "content": "Condition: `Flag metadata` MUST be immutable.",
+                    "RFC 2119 keyword": "MUST",
+                    "children": []
+                }
+            ]
+        },
         {
             "id": "Requirement 1.5.1",
             "machine_id": "requirement_1_5_1",
@@ -263,6 +285,20 @@
                 }
             ]
         },
+        {
+            "id": "Requirement 2.2.9",
+            "machine_id": "requirement_2_2_9",
+            "content": "The `provider` SHOULD populate the `resolution details` structure's `flag metadata` field.",
+            "RFC 2119 keyword": "SHOULD",
+            "children": []
+        },
+        {
+            "id": "Requirement 2.2.10",
+            "machine_id": "requirement_2_2_10",
+            "content": "`flag metadata` MUST be a structure supporting the definition of arbitrary properties, with keys of type `string`, and values of type `boolean | string | number`.",
+            "RFC 2119 keyword": "MUST",
+            "children": []
+        },
         {
             "id": "Requirement 2.3.1",
             "machine_id": "requirement_2_3_1",

specification/sections/01-flag-evaluation.md

@@ -219,6 +219,20 @@ It's recommended to provide non-blocking mechanisms for flag evaluation, particu
 
 > 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.
 
+##### Requirement 1.4.13
+
+> 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.
+
+This `flag metadata` field is intended as a mechanism for providers to surface additional information about a feature flag (or its evaluation) beyond what is defined within the OpenFeature spec itself. The primary consumer of this information is a provider-specific hook.
+
+##### Condition 1.4.14
+
+> The implementation language supports a mechanism for marking data as immutable.
+
+###### Conditional Requirement 1.4.14.1
+
+> Condition: `Flag metadata` **MUST** be immutable.
+
 #### Evaluation Options
 
 ##### Requirement 1.5.1

specification/sections/02-providers.md

@@ -119,6 +119,13 @@ ResolutionDetails<number> resolveNumberValue(string flagKey, number defaultValue
 // example structure flag value resolution with generic argument
 ResolutionDetails<MyStruct> resolveStructureValue(string flagKey, MyStruct defaultValue, context: EvaluationContext);
 ```
+##### Requirement 2.2.9
+
+> The `provider` **SHOULD** populate the `resolution details` structure's `flag metadata` field. 
+
+##### Requirement 2.2.10
+
+> `flag metadata` **MUST** be a structure supporting the definition of arbitrary properties, with keys of type `string`, and values of type `boolean | string | number`.
 
 #### 2.3. Provider hooks
 

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 ([flag metadata](#flag-metadata))
 
 ### 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 ([flag metadata](#flag-metadata), optional)
 
 A set of pre-defined reasons is enumerated below:
 
@@ -85,3 +87,9 @@ An enumerated error code represented idiomatically in the implementation languag
 A structure containing the following fields:
 
 - hooks (one or more [hooks](./sections/04-hooks.md), optional)
+
+### Flag Metadata
+
+A structure which supports definition of arbitrary properties, with keys of type `string`, and values of type `boolean`, `string`, or `number`.
+
+This structure is populated by a provider for use by an [Application Author](./glossary.md#application-author) (via the [Evaluation API](./glossary.md#evaluation-api)) or an [Application Integrator](./glossary.md#application-integrator) (via [hooks](./sections/04-hooks.md)).