Skip to content

OFEP-007: Surfacing flag metadata #169

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

Merged
beeme1mr merged 11 commits into from
Jan 23, 2023
Merged

OFEP-007: Surfacing flag metadata #169

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
91f7942
OFEP-007: Surfacing flag metadata
moredip Dec 19, 2022
9910876
fix numbering, levels
moredip Dec 19, 2022
84b930b
run `make` to generate specification.json
moredip Dec 19, 2022
67ae5f6
preserve section numbering
moredip Jan 11, 2023
10e622c
PR feedback
moredip Jan 11, 2023
affd2ad
lint
moredip Jan 11, 2023
ca64517
Update specification/sections/01-flag-evaluation.md
moredip Jan 13, 2023
b825631
break up into two requirements
moredip Jan 16, 2023
05852eb
Merge remote-tracking branch 'origin/main' into pete/provider-metadata
moredip Jan 16, 2023
e722f12
update spec json
moredip Jan 16, 2023
4968a37
Update specification/types.md
moredip Jan 16, 2023
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
29 changes: 29 additions & 0 deletions specification.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,28 @@
"RFC 2119 keyword": "MAY",
"children": []
},
{
"id": "Requirement 1.4.13",
"machine_id": "requirement_1_4_13",
"content": "If the `flag metadata` field in the `flag resolution` structure returned by the configured `provider` is set, the `evaluation details` structure's `flag metadata` field MUST contain that value. Otherwise, it MUST contain an empty record.",
"RFC 2119 keyword": "MUST",
"children": []
},
{
"id": "Condition 1.4.14",
"machine_id": "condition_1_4_14",
"content": "The implementation language supports a mechanism for marking data as immutable.",
"RFC 2119 keyword": null,
"children": [
{
"id": "Conditional Requirement 1.4.14.1",
"machine_id": "conditional_requirement_1_4_14_1",
"content": "Condition: `Flag metadata` MUST be immutable.",
"RFC 2119 keyword": "MUST",
"children": []
}
]
},
{
"id": "Requirement 1.5.1",
"machine_id": "requirement_1_5_1",
Expand Down Expand Up @@ -263,6 +285,13 @@
}
]
},
{
"id": "Requirement 2.2.9",
"machine_id": "requirement_2_2_9",
"content": "The `provider` SHOULD populate the `resolution details` structure's `flag metadata` field. `flag metadata` MUST be a structure supporting the definition of arbitrary properties, with keys of type `string`, and values of type `boolean | string | number`.",
"RFC 2119 keyword": "MUST",
Comment thread
moredip marked this conversation as resolved.
"children": []
},
{
"id": "Requirement 2.3.1",
"machine_id": "requirement_2_3_1",
Expand Down
14 changes: 14 additions & 0 deletions specification/sections/01-flag-evaluation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -219,6 +219,20 @@ It's recommended to provide non-blocking mechanisms for flag evaluation, particu

> In cases of abnormal execution, the `evaluation details` structure's `error message` field **MAY** contain a string containing additional details about the nature of the error.

##### Requirement 1.4.13

> If the `flag metadata` field in the `flag resolution` structure returned by the configured `provider` is set, the `evaluation details` structure's `flag metadata` field **MUST** contain that value. Otherwise, it **MUST** contain an empty record.
Comment thread
toddbaert marked this conversation as resolved.

This `flag metadata` field is intended as a mechanism for providers to surface additional information about a feature flag (or it's evaluation) beyond what is defined within the OpenFeature spec itself. The primary consumer of this information is a provider-specific hook.
Comment thread
moredip marked this conversation as resolved.
Outdated

##### Condition 1.4.14

> The implementation language supports a mechanism for marking data as immutable.

###### Conditional Requirement 1.4.14.1

> Condition: `Flag metadata` **MUST** be immutable.

#### Evaluation Options

##### Requirement 1.5.1
Expand Down
5 changes: 5 additions & 0 deletions specification/sections/02-providers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,11 @@ ResolutionDetails<number> resolveNumberValue(string flagKey, number defaultValue
// example structure flag value resolution with generic argument
ResolutionDetails<MyStruct> resolveStructureValue(string flagKey, MyStruct defaultValue, context: EvaluationContext);
```
##### Requirement 2.2.9

> The `provider` **SHOULD** populate the `resolution details` structure's `flag metadata` field.

> `flag metadata` **MUST** be a structure supporting the definition of arbitrary properties, with keys of type `string`, and values of type `boolean | string | number`.
Comment thread
moredip marked this conversation as resolved.

#### 2.3. Provider hooks

Expand Down
8 changes: 8 additions & 0 deletions specification/types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ A structure representing the result of the [flag evaluation process](./glossary.
- error message (string, optional)
- reason (string, optional)
- variant (string, optional)
- flag metadata ([flag metadata](#flag-metadata))

### Resolution Details

Expand All @@ -50,6 +51,7 @@ A structure which contains a subset of the fields defined in the `evaluation det
- error message (string, optional)
- reason (string, optional)
- variant (string, optional)
- flag metadata ([flag metadata](#flag-metadata), optional)
Comment thread
moredip marked this conversation as resolved.

A set of pre-defined reasons is enumerated below:

Expand Down Expand Up @@ -85,3 +87,9 @@ An enumerated error code represented idiomatically in the implementation languag
A structure containing the following fields:

- hooks (one or more [hooks](./sections/04-hooks.md), optional)

### Flag Metadata

A structure supports definition of arbitrary properties, with keys of type `string`, and values of type `boolean`, `string`, or `number`.
Comment thread
moredip marked this conversation as resolved.
Outdated

This structure is populated by a provider for use by an [Application Author](./glossary.md#application-author) (via the [Evaluation API](./glossary.md#evaluation-api)) or an [Application Integrator](./glossary.md#application-integrator) (via [hooks](./sections/04-hooks.md)).