DOCSEARCHbyAlgolia
Submit Docs

OpenFeature Specification

repository·main·Indexed 22 days ago

https://github.com/open-feature/spec

A vendor-agnostic, community-driven open specification providing a unified API for feature flagging. It allows developers to switch between different feature flag providers without changing application code. The specification includes guidelines for compliance, stability statuses (Experimental, Hardening, Stable), and detailed requirements for SDK implementations, including the use of in-memory and multi-providers, as well as validation tools like the Repo Parser and Gherkin-based test assets.

Tokens
19.6K
Snippets
34
Records
82
Agent score
79%

What's inside OpenFeature

  1. Overview of the OpenFeature Specification

    main

    OpenFeature is an open specification that provides a vendor-agnostic, community-driven API for feature flagging. It allows developers to use a unified API that works with various feature flag management tools or in-house solutions without being locked into a specific vendor.

    The specification is designed around several core principles:

    • Compatibility: Works with existing feature flag offerings.
    • Simplicity: Provides simple, understandable APIs.
    • Agnosticism: Both vendor-agnostic and language-agnostic.
    • Minimalism: Low or no dependencies.
    • Extensibility: Designed to be extended.

    Note that the OpenFeature SDK provides the mechanism for interfacing with an external evaluation engine in a vendor-agnostic way, but the SDK itself does not handle the flag evaluation logic.

  2. Understand the OpenFeature test asset structure

    main
    The OpenFeature specification uses structured JSON test data (test-flags.json) and Gherkin scenarios to validate implementations. The test data is organized into categories to cover standard behavior, edge cases (like zero/empty values), targeting logic via CEL expressions, and disabled flags. This allows developers to verify that their SDK or provider correctly handles various flag types and targeting scenarios without manual data creation.

  3. What is the OpenFeature Remote Evaluation Protocol (OFREP)?

    main

    The OpenFeature Remote Evaluation Protocol (OFREP) is a unified feature flag evaluation protocol designed to adhere to OpenFeature semantics. It provides a standardized way to perform feature flag evaluations remotely.

    Development and discussions for OFREP are managed in the dedicated OpenFeature OFREP repository. The initiative is supported by a working group focused on:

    • Feature flag evaluation protocol
    • Telemetry enrichment of evaluations
    • Reference implementations of the protocol

    Developers interested in contributing or discussing the protocol can join the #openfeature-remote-evaluation-protocol channel on the CNCF Slack workspace.

  4. What is a Feature Provider?

    main

    A Provider acts as a 'translator' between the OpenFeature Evaluation API used by application authors and the underlying Flag Management System (FMS) that stores and evaluates flags.

    Providers can wrap vendor SDKs, embed REST clients, or read flags from local files. Their primary responsibility is to implement methods that resolve flag values and return resolution details. They may also transform the evaluation context for dynamic evaluation, provide insight into why a flag was resolved a certain way, and expose configuration options for the associated FMS.

  5. What is Evaluation Context?

    main

    The evaluation context provides ambient information used during flag evaluation. This data is used by providers for targeting, such as rule-based evaluation, overrides for specific subjects, or fractional flag evaluation. It can contain information about the end-user, the application, the host, or any other relevant data (e.g., email, locale, or time of day).

    Key components of the context include:

    • Targeting Key: A unique string identifying the subject (e.g., a user or service) of the evaluation. Providers often require this for fractional rollouts or user-specific overrides.
    • Custom Fields: Key-value pairs where keys are string and values are boolean | string | number | datetime | structure.

  6. Understand the relationship between Clients and Providers

    main

    In OpenFeature, the evaluation process is split between two main abstractions:

    • Client: A lightweight abstraction that provides functions to evaluate feature flags. A client is associated with a single Provider.
    • Provider: An SDK-compliant implementation that resolves flag values from a specific Flag Management System (e.g., a SaaS vendor or in-house infra). It allows the system to be used via the standard Evaluation API.

    Domain Binding: You can use a Domain (an identifier) to logically bind clients with providers. This allows an application to use multiple providers simultaneously. Domain binding is dynamic; a client can be re-bound to a different provider during the application's lifetime.

  7. Understand Flagging specifics: Flags, Variants, and Values

    main

    The core components of a feature flag system include:

    • Flag: A single pivot point of logic with a specific type (e.g., string, boolean, json). Identified by a Flag Key.
    • Variant: A semantic identifier for a value. This allows you to refer to a specific version of a feature without passing the full (potentially large) value through the logic.
    • Values: The actual data associated with a variant. These must adhere to the flag's defined type.

    Example of Variants and Values: For a flag named header-order:

    • Variant reverse has value [5,4,3,2,1]
    • Variant wonky has value [3,5,2,1,4]
    • Variant standard has value [1,2,3,4,5]

  8. Handle context reconciliation with RECONCILING and CONTEXT_CHANGED events

    main

    In implementations using the static-context paradigm, providers emit specific events during the reconciliation of the evaluation context:

    1. PROVIDER_RECONCILING: Emitted while the provider's on context changed function is executing. This is useful for showing loading indicators.
    2. PROVIDER_CONTEXT_CHANGED: Emitted when the on context changed function terminates normally. This signals that the context has updated and flags should be re-evaluated (e.g., to trigger UI repaints).
    3. PROVIDER_ERROR: Emitted if the on context changed function terminates abnormally during reconciliation.

    Note: If the provider reconciles synchronously, the RECONCILING event may be skipped.

  9. Choose a signal emission pattern for telemetry hooks

    main

    When implementing observability hooks, choose one of the following three patterns for emitting OpenTelemetry signals:

    1. Span Events (Recommended): Leverages existing trace configuration with minimal overhead. It maintains trace context relationships but requires an active span to function.
    2. Event Logging: Works independently of active spans and aligns with emerging OpenTelemetry directions. It is suitable for environments without tracing but requires an event exporter.
    3. Standalone Spans: Provides detailed timing and full lifecycle control by creating one span per evaluation. This can increase overhead and clutter trace visualizations at scale.

    Note: While Span Events are currently recommended, OpenTelemetry is trending toward log-based events.

  10. Understand Evaluation Context precedence and merging

    main

    When multiple sources provide evaluation context, the SDK merges them using a specific precedence order. If duplicate keys exist, the source with higher precedence overwrites the values from lower precedence sources.

    Precedence Order (Lowest to Highest):

    1. API (global): Static data like application ID or hostname.
    2. Transaction: Data specific to a single unit of work (e.g., a request).
    3. Client: Data associated with a specific OpenFeature Client.
    4. Invocation: Data provided at the specific moment of a flag evaluation call.
    5. Before Hooks: Data mutated or added by before hooks (highest precedence).

  11. Understand Resolution Details (for Provider Authors)

    main

    The Resolution Details structure is used by Provider Authors to define the data returned when resolving flag values. It is a subset of Evaluation Details and is not exposed to the Application Author.

    Fields:

    • value (boolean | string | number | structure, required)
    • error code (error code, optional)
    • error message (string, optional)
    • reason (string, optional)
    • variant (string, optional)
    • flag metadata (flag metadata, optional)

    Resolution Reason

    Providers use the reason field to explain how a value was determined. While you can use any string, the following pre-defined reasons are available:

    ReasonExplanation
    STATICThe resolved value is static (no dynamic evaluation).
    DEFAULTThe resolved value fell back to a pre-configured value (no dynamic evaluation occurred or dynamic evaluation yielded no result).
    TARGETING_MATCHThe resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting.
    SPLITThe resolved value was the result of pseudorandom assignment.
    CACHEDThe resolved value was retrieved from a cache.
    DISABLEDThe resolved value was the result of the flag being disabled in the management system.
    UNKNOWNThe reason for the resolved value could not be determined.
    STALEThe resolved value is non-authoritative or possibly out of date
    ERRORThe resolved value was the result of an error.
    enum Reason {
    Static,
    Default,
    TargetingMatch,
    Split,
    Cached,
    Unknown,
    Stale,
    Error,
    Other(String)
}

let myReason = Reason::Other("my-reason".to_string());

  12. Use Hook context to access evaluation data

    main

    The HookContext is provided to every hook stage to allow access to information about the current flag evaluation and to propagate data between stages.

    Required properties in HookContext:

    • flag key: The identifier of the flag being evaluated.
    • flag value type: The expected type of the flag value.
    • evaluation context: The merged evaluation context (including any modifications made by previous before hooks).
    • default value: The fallback value provided by the application.
    • hook data: A mutable structure used to share data between the different stages of the same hook instance.

    Immutability Rules:

    • The flag key, flag type, and default value MUST be immutable.
    • In the dynamic-context paradigm, the evaluation context must be mutable only within the before hook.
    • In the static-context paradigm, the evaluation context is not returned/modified by the before hook.