Specification Document for GO Feature Flag OpenFeature Providers

Overview​

GO Feature Flag does not ship its own SDKs. Applications talk to it through OpenFeature SDKs plus a GO Feature Flag provider. Those providers exist in eight languages, written by different people at different times, and they have drifted apart — not only in naming and defaults, but in wire format, error semantics and evaluation results.

This document is the contract every server-side GO Feature Flag provider must satisfy so that the same flag, evaluated with the same context, returns the same result in every language.

It is written to be checked mechanically. Every normative statement carries a stable identifier, an RFC 2119 keyword and a severity, so an automated audit can walk a provider's source and emit a per-requirement verdict.

Relationship to other documents​

• If you are writing a new provider, start with Implementing a GO Feature Flag Provider. It gives the component shape, build order and complete wire payloads that this document deliberately omits, and links back here for the rules. This document tells you what must be true; that one tells you what to build.

1. Scope and conventions​

1.1 Requirement keywords​

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT and MAY are to be interpreted as described in RFC 2119.

1.2 Requirement identifiers​

Every requirement has a stable identifier of the form GOFF-<AREA>-<NNN>. Identifiers are never reused or renumbered; a withdrawn requirement is marked as such and its number retired.

1.3 Conformance tiers​

Not every requirement applies to every provider. Each section declares a tier:

A requirement outside a provider's tiers is reported N/A, never FAIL. In particular, a provider written in Go links the evaluation engine directly and is N/A for the whole of §10 — it does not fail for declining to use WebAssembly.

Where the target language's OpenFeature SDK offers no equivalent capability at all — for example, an SDK with no Tracking API — the corresponding requirements are also N/A.

1.4 Severity​

1.5 Deferring to the language SDK​

Where the target language's OpenFeature SDK defines a behaviour — the canonical object type, the ErrorCode enumeration, provider status transitions, event types, hook stage ordering — the provider MUST follow its SDK. Those SDKs are implementations of one shared OpenFeature specification, so deferring to them converges rather than diverges.

Where a divergence is a language accident rather than an SDK decision, this specification overrides it. Known accidents, called out so implementers know the override is deliberate:

• Python: isinstance(True, int) is True, so a boolean silently satisfies an integer resolver. See GOFF-EVAL-004.
• Java: a JSON number above Integer.MAX_VALUE decodes to Long and currently fails both the integer and the double resolver.
• .NET: GetInt32() throws FormatException on a non-integral number rather than producing a type mismatch.

1.6 Evaluation engine version​

All providers MUST evaluate using the same engine build. Two providers on different engine versions can return different values for the same flag and context — a divergence no other requirement in this document would detect, because all of them would still pass.

Evidence for GOFF-ENG-001 is the pinned version declaration, not the binary itself. Engine artefacts are commonly fetched at build time and absent from a source checkout, so an audit verifies the pin and the code path that consumes it.

1.7 Delegated behaviour​

A provider MUST be treated as accountable for the observable behaviour of any library it delegates to, including a generic OFREP client. Deferring to a dependency is a legitimate implementation choice, but it does not transfer conformance: if the delegate returns TYPE_MISMATCH where this specification requires a value, the provider is non-conformant.

This does not conflict with §1.5. Deferring to the OpenFeature SDK for the shape of a type or the name of an error code is required. Inheriting a third-party client's behaviour where this specification is explicit is not.

An audit SHOULD record whether the remediation for such a finding lies upstream, since that materially changes who can fix it and how quickly.

2. Provider identity — GOFF-META​

Tier: Core

3. Configuration — GOFF-CFG​

Tier: Core

Option names are RECOMMENDED, not normative: a provider SHOULD use the canonical name adapted to its language's conventions — including a unit suffix where the language favours one, such as flagChangePollingIntervalMs — and MAY retain an existing name as an alias. Option semantics and default values are normative — they have real operational consequences, and divergent defaults are how a fleet ends up behaving inconsistently.

3.1 Canonical options​

A REQUIRED option that is absent is a GOFF-CFG-003 failure. A RECOMMENDED option that is absent is reported against its own requirement, not against GOFF-CFG-003.

† wasmEvaluatorPoolSize applies only where the runtime supports parallel execution. On a single-threaded runtime it is N/A, for the reason given in GOFF-WASM-009.

3.2 Requirements​

4. Lifecycle — GOFF-LIFE​

Tier: Core

5. Provider events and status — GOFF-EVT​

Tier: Core

6. Evaluation API — GOFF-EVAL​

Tier: Core

7. Evaluation context — GOFF-CTX​

Tier: Core

7.1 The gofeatureflag reserved namespace​

The gofeatureflag context key is a shared namespace with three fields:

8. Remote evaluation — GOFF-REM​

Tier: Remote

Remote evaluation uses the OpenFeature Remote Evaluation Protocol.

9. In-process evaluation — GOFF-IP​

Tier: In-process

In-process evaluation is defined by behaviour, not by transport. A provider may embed the engine through WebAssembly or, where the language permits, link it directly. Both MUST produce identical results.

9.1 Flag configuration retrieval​

9.2 Polling and refresh​

9.3 Evaluation​

10. WebAssembly ABI — GOFF-WASM​

Tier: WASM. Providers that link the engine directly are N/A for this section.

The module exposes one entry point. The host writes a JSON request into linear memory, calls evaluate, and reads a JSON response back out.

1. Serialize the input to UTF-8 bytes
2. ptr = malloc(byteLength + 1)
3. write bytes at ptr, followed by a NUL terminator
4. packed = evaluate(ptr, byteLength)      // byteLength, NOT including the terminator
5. outPtr = (packed >> 32) & 0xFFFFFFFF
   outLen =  packed        & 0xFFFFFFFF
6. read outLen bytes at outPtr and parse as JSON   ← BEFORE any further call
7. free(ptr)

10.1 Built-in safeguards​

Binaries after 0.2.3 carry a 1 MB shadow stack and return a structured PARSE_ERROR instead of trapping when input exceeds a guard:

A guard breach surfaces as PARSE_ERROR, which §16 turns into a remote evaluation. That is the intended outcome: the relay proxy evaluates on a full stack and has no equivalent limit, so a context the embedded engine cannot handle still resolves correctly.

Input and output shapes are given in Appendix B.3.

11. Error model — GOFF-ERR​

Tier: Core

11.1 Engine error codes​

PROVIDER_NOT_READY, FLAG_NOT_FOUND, PARSE_ERROR, TYPE_MISMATCH, GENERAL, INVALID_CONTEXT, TARGETING_KEY_MISSING, and the GO Feature Flag-specific FLAG_CONFIG.

11.2 Requirements​

12. Hooks — GOFF-HOOK​

Tier: Core

13. Data collection — GOFF-COLL​

Tier: Core

Evaluation and tracking events are batched and posted to the relay proxy.

13.1 Envelope​

{
  "meta": { "provider": "python", "openfeature": true },
  "events": [ ... ]
}

13.2 Feature event​

contextKind is decided as follows. The table is normative — it exists because a truthiness test and an identity test agree on the common cases and diverge on the rest.

The last-but-one row is the only one not decided by an identity test on anonymous, because there is no attribute to read: with no evaluation context there is also no targeting key, so there is nobody to attribute the evaluation to and anonymousUser is the honest bucket.

13.3 Exporter metadata​

13.4 Buffering and flushing​

13.5 What is collected​

14. Tracking — GOFF-TRACK​

Tier: Core. N/A where the language's OpenFeature SDK has no Tracking API.

15. Authentication — GOFF-AUTH​

Tier: Core

16. Remote fallback — GOFF-FALLBACK​

Tier: In-process

When local evaluation fails in a way that suggests the provider — rather than the flag — is at fault, the relay proxy is authoritative and reachable. Falling back to it converts a local failure into a correct answer.

Where a fallback follows a WebAssembly trap, the ordering is: catch the trap, discard and rebuild the instance (GOFF-WASM-008), then fall back. The provider MUST NOT retry locally on the fresh instance first.

17. Remote cache (optional)​

Tier: Optional.

A provider MAY cache remote evaluation results locally. If it does, the following apply; if it does not, they are N/A and no feature events are produced in remote mode.

Appendix A — Endpoint reference​

A.1 Normative​

A.2 Superseded​

These remain functional but MUST NOT be used by a conformant provider.

Appendix B — Conformance fixtures​

These fixtures are canonical. They live in the go-feature-flag repository and providers MUST test against them unmodified. A provider whose local copy has diverged from canon is non-conformant regardless of whether its own tests pass.

B.1 Canonical evaluation context​

{
  "targetingKey": "d45e303a-38c2-11ed-a261-0242ac120002",
  "email": "john.doe@gofeatureflag.org",
  "firstname": "john",
  "lastname": "doe",
  "anonymous": false,
  "professional": true,
  "rate": 3.14,
  "age": 30,
  "company_info": { "name": "my_company", "size": 120 },
  "labels": ["pro", "beta"]
}

B.2 In-process expected results​

Source: openfeature/providers/python-provider/tests/mock_responses/config/valid-all-types.json, evaluated with the context above. evaluationContextEnrichment is {"env": "production"}.

Notes that catch real bugs:

• string_key resolves via its default rule with no targeting match, so the reason is STATIC, not TARGETING_MATCH.
• string_key sets trackEvents: false and therefore MUST NOT produce a feature event (GOFF-COLL-022).
• A disabled flag returns the caller's default with variant SdkDefault — not defaultSdk, and not a null variant.

B.3 Engine ABI vectors​

Source: cmd/wasm/testdata/. Input:

{
  "flagKey": "TEST",
  "flag": {
    "variations": { "enable": true, "disable": false },
    "targeting": [
      {
        "name": "targetingID rule",
        "query": "targetingKey eq \"random-key\"",
        "percentage": { "enable": 90, "disable": 10 }
      }
    ],
    "defaultRule": { "variation": "disable" },
    "metadata": { "description": "test flag", "type": "boolean" }
  },
  "evalContext": { "targetingKey": "random-key", "age": 42 },
  "flagContext": {
    "evaluationContextEnrichment": { "env": "production" },
    "defaultSdkValue": false
  }
}

Output:

{
  "trackEvents": true,
  "variationType": "enable",
  "failed": false,
  "version": "",
  "reason": "TARGETING_MATCH_SPLIT",
  "errorCode": "",
  "value": true,
  "cacheable": true,
  "metadata": {
    "description": "test flag",
    "evaluatedRuleName": "targetingID rule",
    "type": "boolean"
  }
}

Two further vectors are canonical: an empty targeting key against a bucketing flag yields errorCode: "TARGETING_KEY_MISSING" with variationType: "SdkDefault", and a malformed input yields errorCode: "PARSE_ERROR" with value: null. Both MUST trigger the behaviour of §16 where applicable.

B.4 Remote integration fixture​

openfeature/provider_tests/flags.yaml drives the cross-language integration suites. Its variations are named Default, "False" and "True"; the canonical context above matches the targeting rule on every flag, so remote evaluation returns variant True. Each flag carries metadata description and pr_link, which MUST be surfaced as flag metadata unmodified.

Appendix C — Conformance checklist and report format​

C.1 Verdicts​

Each requirement is reported as PASS, FAIL or N/A. N/A is reserved for requirements outside the provider's declared tiers, or capabilities its SDK does not offer. A requirement that applies but cannot be verified is FAIL, not N/A.

Vacuous satisfaction. A requirement whose precondition cannot occur because the governing capability is absent MUST inherit the verdict of that capability's requirement. Without this rule a provider that implements nothing accumulates free passes: every MUST NOT in a section it has not built is trivially unviolated. For example, a provider with no fallback path fails GOFF-FALLBACK-001, and GOFF-FALLBACK-003 and -006 — both prohibitions — inherit that FAIL rather than passing.

Accidental satisfaction. A requirement met by coincidence rather than by intent MUST be reported as PASS with a note. A provider that performs no trackability check at all satisfies GOFF-COLL-020 and -021 while failing -022; recording the first two as unqualified passes hides that the next refactor will break them.

C.2 Report format​

A conformance report MUST contain four parts, in order:

1. a header stating the specification version, the provider and version audited, and the declared tier set — every N/A must trace back to it;
2. a single verdict line;
3. findings grouped by severity, most severe first, each citing a requirement identifier and a source location;
4. a per-requirement verdict table covering every identifier in the specification, including passes, since PASS with a note is a meaningful outcome under §C.1.

GO Feature Flag Provider Specification 1.0 — <provider> <version>
TIERS: Core, Remote, In-process, WASM  (Optional/§17: no cache → N/A;
                                        §14: SDK has no Tracking API → N/A)
VERDICT: NON-CONFORMANT — 2 Critical, 5 Major, 3 Minor (118 PASS, 10 FAIL, 9 N/A)

CRITICAL
  GOFF-IP-007   304 without ETag wipes the flag map        src/evaluator/inprocess.ts:142
  GOFF-CTX-006  Enrich hook replaces the gofeatureflag map src/hook/enrich.ts:18

MAJOR
  ...

PER-REQUIREMENT
  GOFF-META-001  PASS   src/provider.ts:25
  GOFF-COLL-020  PASS   (accidental — no trackability check exists at all)
  GOFF-FALLBACK-003  FAIL  (inherited: §16 unimplemented)
  ...

Two further finding classes MUST be reported when present, because neither has a natural home in a requirement-keyed list:

• Documentation contradicting code. Cite both locations. Where the contradiction is an option that is declared but never read, report it as GOFF-CFG-009; otherwise report it as a Minor finding with both citations and no requirement identifier.
• Tests that assert non-conformant behaviour. A green suite pinning a defect raises the cost of remediation and indicates the behaviour was deliberate. Name the test alongside the finding it protects.

C.3 Auditing method​

The procedure for producing such a report — which files to read, in what order, and how to decide N/A — is maintained alongside the source rather than here, so it can evolve without a specification revision.

One rule is normative because it was learned the hard way: source is authoritative over documentation. During the audits that produced this specification, every provider's own README, doc comments or agent instructions were wrong about that provider's behaviour, and in several cases documented a default that no code path ever assigned. A contradiction between a provider's documentation and its code MUST be reported as a finding in its own right.

Appendix D — Known gaps​

This appendix is populated in a follow-up revision, once the corresponding issues have been filed against each provider repository. Each row will cite its tracking issue.