From d0a87da15f892603296565e2bd8a9b50b399bb0d Mon Sep 17 00:00:00 2001 From: Todd Baert Date: Tue, 26 Sep 2023 09:19:11 -0400 Subject: [PATCH] chore: clarify eval details funcs/structs (#209) Signed-off-by: Todd Baert --- .markdownlint.yml | 2 ++ specification/README.md | 3 ++- specification/sections/01-flag-evaluation.md | 7 +++++++ specification/sections/03-evaluation-context.md | 3 ++- specification/types.md | 9 ++++++++- 5 files changed, 21 insertions(+), 3 deletions(-) diff --git a/.markdownlint.yml b/.markdownlint.yml index 93f623b1..d130710e 100644 --- a/.markdownlint.yml +++ b/.markdownlint.yml @@ -8,3 +8,5 @@ MD024: siblings_only: true MD025: front_matter_title: "" +MD028: false # no blank lines in block quote - disabling b/c it fires on 2 consecutive block quotes :/ + 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