Skip to content

Commit

Permalink
chore: clarify eval details funcs/structs (#209)
Browse files Browse the repository at this point in the history
Signed-off-by: Todd Baert <[email protected]>
  • Loading branch information
toddbaert authored Sep 26, 2023
1 parent e2eb2b4 commit d0a87da
Show file tree
Hide file tree
Showing 5 changed files with 21 additions and 3 deletions.
2 changes: 2 additions & 0 deletions .markdownlint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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 :/

3 changes: 2 additions & 1 deletion specification/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,4 +75,5 @@ Put simply:

> These features are stable and battle-hardened.
NOTE: No explicit status = `Experimental`
> [!NOTE]
> No explicit status = `Experimental`
7 changes: 7 additions & 0 deletions specification/sections/01-flag-evaluation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
3 changes: 2 additions & 1 deletion specification/sections/03-evaluation-context.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
9 changes: 8 additions & 1 deletion specification/types.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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

Expand Down

0 comments on commit d0a87da

Please sign in to comment.