From 9760d8fbc679f36064bbf6a22d708d1fc4125921 Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Mon, 25 Sep 2023 12:43:17 -0400 Subject: [PATCH] chore: clarify eval details funcs/structs * add details about evaluation details * add note about advanced type usage * convert all notes to proper markdown notes Signed-off-by: Todd Baert --- specification/README.md | 3 ++- specification/sections/01-flag-evaluation.md | 7 +++++++ specification/sections/03-evaluation-context.md | 3 ++- specification/types.md | 9 ++++++++- 4 files changed, 19 insertions(+), 3 deletions(-) diff --git a/specification/README.md b/specification/README.md index 57d0d65f..b344673b 100644 --- a/specification/README.md +++ b/specification/README.md @@ -75,4 +75,5 @@ Put simply: > These features are stable and battle-hardened. -NOTE: No explicit status = `Experimental` +> [!NOTE] +> No explicit status = `Experimental` diff --git a/specification/sections/01-flag-evaluation.md b/specification/sections/01-flag-evaluation.md index 0b301041..d04701f6 100644 --- a/specification/sections/01-flag-evaluation.md +++ b/specification/sections/01-flag-evaluation.md @@ -232,6 +232,13 @@ See [types](../types.md) for details. [![hardening](https://img.shields.io/static/v1?label=Status&message=hardening&color=yellow)](https://github.com/open-feature/spec/tree/main/specification#hardening) +The _detailed evaluation_ functions behave similarly to the standard flag evaluation functions, but provide additional metadata useful for telemetry, troubleshooting, debugging, and advanced integrations. + +> [!NOTE] +> Metadata included in the `evaluation details` should be considered "best effort", since not all providers will be able to provide these details (such as the reason a flag resolved to a particular value). + +see: [evaluation details](../types.md#evaluation-details) type + #### Condition 1.4.1 > The implementation uses the dynamic-context paradigm. diff --git a/specification/sections/03-evaluation-context.md b/specification/sections/03-evaluation-context.md index 1cbfc3c3..3bee9503 100644 --- a/specification/sections/03-evaluation-context.md +++ b/specification/sections/03-evaluation-context.md @@ -16,7 +16,8 @@ The context might contain information about the end-user, the application, the h ### 3.1 Fields -NOTE: Field casing is not specified, and should be chosen in accordance with language idioms. +> [!NOTE] +> Field casing is not specified, and should be chosen in accordance with language idioms. see: [types](../types.md) diff --git a/specification/types.md b/specification/types.md index 068806c7..13880c9e 100644 --- a/specification/types.md +++ b/specification/types.md @@ -42,6 +42,11 @@ A structure representing the result of the [flag evaluation process](./glossary. - variant (string, optional) - flag metadata ([flag metadata](#flag-metadata)) +> [!NOTE] +> Some type systems feature useful constraints that can enhance the ergonomics of the `evaluation details` structure. +> For example, in the case of an unsuccessful evaluation, `error code`, `reason`, and `error message` will be set, and variant will not. +> If the type system of the implementation supports the expression of such constraints, consider defining them. + ### Resolution Details A structure which contains a subset of the fields defined in the `evaluation details`, representing the result of the provider's [flag resolution process](./glossary.md#resolving-flag-values), including: @@ -67,7 +72,9 @@ A set of pre-defined reasons is enumerated below: | STALE | The resolved value is non-authoritative or possibly out of date | | 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. +> [!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. ### Error Code