docs: Add docs about $flag.properties (#965)

docs/reference/flag-definitions.md

@@ -146,7 +146,7 @@ Example of an invalid configuration:
 
 `targeting` is an **optional** property.
 A targeting rule **must** be valid JSON.
-Flagd uses a modified version of [JSON Logic](https://jsonlogic.com/), as well as some custom pre-processing, to evaluate these rules.
+Flagd uses a modified version of [JsonLogic](https://jsonlogic.com/), as well as some custom pre-processing, to evaluate these rules.
 The output of the targeting rule **must** match the name of one of the variants defined above.
 If an invalid or null value is returned by the targeting rule, the `defaultVariant` value is used.
 If no targeting rules are defined, the response reason will always be `STATIC`, this allows for the flag values to be cached, this behavior is described [here](specifications/rpc-providers.md#caching).
@@ -173,7 +173,7 @@ The evaluation context can be accessed in targeting rules using the `var` operat
 | Retrieve property from the evaluation context or use a default | `#!json { "var": ["email", "noreply@example.com"] }` |
 | Retrieve a nested property from the evaluation context         | `#!json { "var": "user.email" }`                     |
 
-> For more information, see the `var` section in the [JSON Logic documentation](https://jsonlogic.com/operations.html#var).
+> For more information, see the `var` section in the [JsonLogic documentation](https://jsonlogic.com/operations.html#var).
 
 #### Conditions
 
@@ -217,10 +217,19 @@ They are purpose built extensions to JsonLogic in order to support common featur
 
 | Function                           | Description                                         | Example                                                                                                                                                                                                                                                                                  |
 | ---------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fractional` (_available v0.6.4+_) | Deterministic, pseudorandom fractional distribution | Logic: `#!json { "fractional" : [ { "var": "email" }, [ "red" , 50], [ "green" , 50 ] ] }` <br>Result: Pseudo randomly `red` or `green` based on the evaluation context property `email`.<br><br>Additional documentation can be found [here](./custom-operations/fractional-operation.md)         |
-| `starts_with`                      | Attribute starts with the specified value           | Logic: `#!json { "starts_with" : [ "192.168.0.1", "192.168"] }`<br>Result: `true`<br><br>Logic: `#!json { "starts_with" : [ "10.0.0.1", "192.168"] }`<br>Result: `false`<br>Additional documentation can be found [here](./custom-operations/string-comparison-operation.md)                      |
-| `ends_with`                        | Attribute ends with the specified value             | Logic: `#!json { "ends_with" : [ "noreply@example.com", "@example.com"] }`<br>Result: `true`<br><br>Logic: `#!json { ends_with" : [ "noreply@example.com", "@test.com"] }`<br>Result: `false`<br>Additional documentation can be found [here](./custom-operations/string-comparison-operation.md) |
-| `sem_ver`                          | Attribute matches a semantic versioning condition   | Logic: `#!json {"sem_ver": ["1.1.2", ">=", "1.0.0"]}`<br>Result: `true`<br><br>Additional documentation can be found [here](./custom-operations/semver-operation.md)                                                                                                                    |
+| `fractional` (_available v0.6.4+_) | Deterministic, pseudorandom fractional distribution | Logic: `#!json { "fractional" : [ { "var": "email" }, [ "red" , 50], [ "green" , 50 ] ] }` <br>Result: Pseudo randomly `red` or `green` based on the evaluation context property `email`.<br><br>Additional documentation can be found [here](./custom-operations/fractional-operation.md).        |
+| `starts_with`                      | Attribute starts with the specified value           | Logic: `#!json { "starts_with" : [ "192.168.0.1", "192.168"] }`<br>Result: `true`<br><br>Logic: `#!json { "starts_with" : [ "10.0.0.1", "192.168"] }`<br>Result: `false`<br>Additional documentation can be found [here](./custom-operations/string-comparison-operation.md).                     |
+| `ends_with`                        | Attribute ends with the specified value             | Logic: `#!json { "ends_with" : [ "noreply@example.com", "@example.com"] }`<br>Result: `true`<br><br>Logic: `#!json { ends_with" : [ "noreply@example.com", "@test.com"] }`<br>Result: `false`<br>Additional documentation can be found [here](./custom-operations/string-comparison-operation.md).|
+| `sem_ver`                          | Attribute matches a semantic versioning condition   | Logic: `#!json {"sem_ver": ["1.1.2", ">=", "1.0.0"]}`<br>Result: `true`<br><br>Additional documentation can be found [here](./custom-operations/semver-operation.md).                                                                                                                   |
+
+#### $flagd properties in the evaluation context
+
+Flagd adds the following properties to the evaluation context that can be used in the targeting rules.
+
+| Property | Description | From version |
+|----------|-------------|--------------|
+| `$flagd.flagKey` | the identifier for the flag being evaluated | v0.6.4 |
+| `$flagd.timestamp`| a unix timestamp (in seconds) of the time of evaluation | v0.6.7 |
 
 ## Shared evaluators
 

docs/reference/specifications/in-process-providers.md

@@ -68,6 +68,7 @@ Note that for the in-process provider only the `sync` package will be relevant,
 
 An in-process flagd provider should provide the feature set offered by [JsonLogic](https://jsonlogic.com) to evaluate flag resolution requests for a given context.
 If available, the JsonLogic library for the chosen technology should be used.
+Additionally, it should also provide the custom JsonLogic evaluators and `$flagd` properties in the evaluation context described below.
 
 ### Custom JsonLogic evaluators
 
@@ -94,6 +95,16 @@ This evaluator selects a variant based on whether the specified property within
 starts/ends with a certain string.
 For more specific implementation guidelines, please refer to [this document](./custom-operations/string-comparison-operation-spec.md).
 
+### $flagd properties in the evaluation context
+
+An in-process flagd provider should also add the following properties to the JsonLogic evaluation context so that users can use them in their targeting rules.
+Conflicting properties in the context will be overwritten by the values below.
+
+| Property | Description |
+|----------|-------------|
+| `$flagd.flagKey` | the identifier for the flag being evaluated |
+| `$flagd.timestamp`| a unix timestamp (in seconds) of the time of evaluation |
+
 ## Provider construction
 
 (**using Go as an example**)