Skip to content

docs: clarify evaluation and resolution details #382

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Rul1an wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: clarify evaluation and resolution details #382

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions specification/types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ A language primitive for representing a date and time, optionally including time

### Evaluation Details

A structure representing the result of the [flag evaluation process](./glossary.md#evaluating-flag-values), and made available in the [detailed flag resolution functions](./sections/01-flag-evaluation.md#14-detailed-flag-evaluation), containing the following fields:
A structure representing the result of the [flag evaluation process](./glossary.md#evaluating-flag-values), and made available in the [detailed flag evaluation functions](./sections/01-flag-evaluation.md#14-detailed-flag-evaluation), containing the following fields:

- flag key (string, required)
- value (boolean | string | number | structure, required)
Expand All @@ -45,6 +45,10 @@ A structure representing the result of the [flag evaluation process](./glossary.
> [!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.

> [!NOTE]
> `evaluation details` are the application-facing result returned from detailed flag evaluation.
> They include the `flag key` supplied to the client, the evaluated value, and other fields derived from the provider's `resolution details` when available, such as `variant`, `reason`, `error code`, `error message`, and `flag metadata`.

### 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 Down Expand Up @@ -91,7 +95,10 @@ enum Reason {
let myReason = Reason::Other("my-reason".to_string());
```

> [!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]
> `resolution details` are the return structure providers send to the SDK.
> Provider Authors return this structure when resolving a flag value.
> Application Authors do not receive the actual `resolution details` object directly; instead, detailed flag evaluation functions return an `evaluation details` object built from the provider's `resolution details` when available, plus SDK-level fields such as `flag key`, default values, and error information.

### Error Code

Expand Down
Loading