Merging context (#117)

* Merging context

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

* Update specification/evaluation-context.md

Co-authored-by: Skye Gill <[email protected]>
Signed-off-by: Skye Gill <[email protected]>
Signed-off-by: Todd Baert <[email protected]>

Co-authored-by: Skye Gill <[email protected]>

Author: toddbaert

specification.json

@@ -286,19 +286,33 @@
             ]
         },
         {
-            "id": "Requirement 3.1",
-            "machine_id": "requirement_3_1",
+            "id": "Requirement 3.1.1",
+            "machine_id": "requirement_3_1_1",
             "content": "The `evaluation context` structure MUST define an optional `targeting key` field of type string, identifying the subject of the flag evaluation.",
             "RFC 2119 keyword": "MUST",
             "children": []
         },
         {
-            "id": "Requirement 3.2",
-            "machine_id": "requirement_3_2",
+            "id": "Requirement 3.1.2",
+            "machine_id": "requirement_3_1_2",
             "content": "The evaluation context MUST support the inclusion of custom fields, having keys of type `string`, and values of type `boolean | string | number | datetime | structure`.",
             "RFC 2119 keyword": "MUST",
             "children": []
         },
+        {
+            "id": "Requirement 3.2.1",
+            "machine_id": "requirement_3_2_1",
+            "content": "The API, Client and invocation MUST have a method for supplying `evaluation context`.",
+            "RFC 2119 keyword": "MUST",
+            "children": []
+        },
+        {
+            "id": "Requirement 3.2.2",
+            "machine_id": "requirement_3_2_2",
+            "content": "Evaluation context MUST be merged in the order: API (global) - client - invocation, with duplicate values being overwritten.",
+            "RFC 2119 keyword": "MUST",
+            "children": []
+        },
         {
             "id": "Requirement 4.1.1",
             "machine_id": "requirement_4_1_1",

specification/sections/03-evaluation-context.md

@@ -20,14 +20,28 @@ NOTE: Field casing is not specified, and should be chosen in accordance with lan
 
 see: [types](../types.md)
 
-#### Requirement 3.1
+#### Requirement 3.1.1
 
 > The `evaluation context` structure **MUST** define an optional `targeting key` field of type string, identifying the subject of the flag evaluation.
 
 The targeting key uniquely identifies the subject (end-user, or client service) of a flag evaluation. Providers may require this field for fractional flag evaluation, rules, or overrides targeting specific users. Such providers may behave unpredictably if a targeting key is not specified at flag resolution.
 
-#### Requirement 3.2
+#### Requirement 3.1.2
 
 > The evaluation context **MUST** support the inclusion of custom fields, having keys of type `string`, and values of type `boolean | string | number | datetime | structure`.
 
 see: [structure](../types.md#structure), [datetime](../types.md#datetime)
+
+### Merging Context
+
+#### Requirement 3.2.1
+
+> The API, Client and invocation **MUST** have a method for supplying `evaluation context`.
+
+API (global) `evaluation context` can be used to supply static data to flag evaluation, such as an application identifier, compute region, or hostname. Client and invocation `evaluation context` are ideal for dynamic data, such as end-user attributes.
+
+#### Requirement 3.2.2
+
+> Evaluation context **MUST** be merged in the order: API (global) -> client -> invocation, with duplicate values being overwritten.
+
+Any fields defined in the client `evaluation context` will overwrite duplicate fields defined globally, and fields defined in the invocation `evaluation context` will overwrite duplicate fields defined in the globally or on the client.