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 <[email protected]>
open-feature · Sep 25, 2023 · 9760d8f · 9760d8f
1 parent e2eb2b4
commit 9760d8f
Show file tree

Hide file tree

Showing 4 changed files with 19 additions and 3 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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