Skip to main content

Providers

Providers are responsible for performing flag evaluations. They provide an abstraction between the underlying flag management system and the OpenFeature SDK. Providers can wrap a vendor SDK, call a bespoke flag evaluation REST API, or even parse some locally stored file to resolve flag values. This allows the underlying flag evaluation logic to be changed without requiring a major code refactor.

An application integrator can register one provider at a time. Registering an additional provider will override any previously configured providers. If no provider is set, OpenFeature will no-op and return the default value passed to the evaluation API.

Providers are set through the evaluation API. They're globally registered and a change affects both new and existing OpenFeature clients.

An example of an OpenFeature provider for a fictional Flags-R-us service.

Implementing Providers

Getting started

To develop a provider, start by confirming that an OpenFeature SDK is available in the language you're interested in. Next, you need to create a new project and include the OpenFeature SDK as a dependency. This can be a new repository or included in an existing contrib repository available under the OpenFeature organization. Finally, you’ll then need to write the provider itself. In most languages, this can be accomplished by implementing the provider interface exported by the OpenFeature SDK.

Naming recommendations

The following naming recommendations can be used to ensure consistency between providers developed among the community.

Repository name

If you're creating a new repository, it's recommended that you use one the following naming conventions:

  • openfeature-provider-<language name>
  • <vender/tool name>-openfeature-provider-<language name>
note

It is not required that a provider be open source, but it's highly recommended.

Artifact name

The name of the artifact will vary based on the package manager. Ultimately, it's up to the publisher to decide what name makes the most sense. However, the following items should be used in the package name:

  • OpenFeature (can also be stylized as openfeature or open-feature)
  • Vender/tool name
  • The word provider should be included in the name

An example of what it could look like in NPM: @openfeature/flagd-provider

Examples

import { Provider, ResolutionDetails, EvaluationContext, JsonValue } from '@openfeature/js-sdk';

export class MyFeatureProvider implements Provider {
readonly metadata = {
name: 'My Feature Provider',
} as const;

resolveBooleanEvaluation(
flagKey: string,
defaultValue: boolean,
context: EvaluationContext
): Promise<ResolutionDetails<boolean>> {
// code to resolve boolean details
}

resolveStringEvaluation(
flagKey: string,
defaultValue: string,
context: EvaluationContext
): Promise<ResolutionDetails<string>> {
// code to resolve string details
}

resolveNumberEvaluation(
flagKey: string,
defaultValue: number,
context: EvaluationContext
): Promise<ResolutionDetails<number>> {
// code to resolve number details
}

resolveObjectEvaluation(
flagKey: string,
defaultValue: JsonValue,
context: EvaluationContext
): Promise<ResolutionDetails<JsonValue>> {
// code to resolve object details
}
}

Checklist

Here is a checklist of important considerations when implementing a provider.

Functional requirements

All resolution methods are implemented (see Provider / FeatureProvider interface in applicable SDK).

Relevant configuration options for the underlying backend are exposed (typically using the provider constructor).

Flag-keys are transformed appropriately for the underlying backend (OpenFeature defines no restrictions in valid flag keys).

Context is transformed appropriately for the underlying backend.

Provider is named according to the naming conventions

Copy as Markdown

Non-functional requirements

Documentation for installation, all behaviors (options, context transformation, flag-key transformation).

Provider is adequately tested.

Provider is added to the documentation site.

Provider releases follow semantic versioning.

Document the version of the OpenFeature specification to which your provider complies.

Copy as Markdown

FAQ

Does my provider's version need to match the spec version to which it complies?

No. You should document the version of the OpenFeature specification your provider complies to, and otherwise use semantic versioning in your artifact numbers.

My backend needs a targeting key (or other user identifier), how can I ensure one exists?

Targeting keys are not required by the Evaluation API. If your backend requires one, you have a couple options:

  • Indicate an error in your provider (this will result in the default value being returned).
  • Generate one automatically.

Be sure to document this behavior.

How should I handle error conditions?

If an error condition is encountered in your provider, an error should be indicated by throwing or returning an error, as language idioms dictate. The SDK will ensure the default value is returned and expose the relevant error data.

My flag system doesn't support flags of a particular type. What should I do?

If your backend system doesn't support a particular flag type, you can:

  • Do a conversion from a type the system supports (for example, store JSON objects in a string, or booleans as 0/1), and document this pattern.
  • Indicate an error in your provider (this will result in the default value being returned).

How can people find my provider?

Please add your provider to the documentation so people can find it!

Where should I put my provider source code?

If you are a vendor and you want to maintain full control over your provider, you should host the provider in your organization's SCM. If you would like your provider to be maintained as a community project, please take a look at our various contrib repositories. We encourage you to make your code open source, but obviously it's your decision.

Where should I publish my provider artifact?

You should publish your provider on the appropriate package management repository for your language, keeping in mind the naming conventions. Our contrib repositories publish all their artifacts as part of their release processes.