feat: implement ADR-0008 event stream support in OpenAPI spec

[jonathannorris]

Summary

• Implements the OpenAPI spec changes defined in ADR-0008, scoped to static-context providers using the bulk evaluation endpoint (POST /ofrep/v1/evaluate/flags)
• eventStreams is intentionally limited to bulkEvaluationSuccess — SSE support for dynamic-context providers using single-flag evaluations is deferred to a follow-up ADR
• Bumps OFREP version from 0.2.0 to 0.3.0
• Adds eventStreams to bulkEvaluationSuccess, flagConfigEtag / flagConfigLastModified query parameters to the bulk eval endpoint, and new schemas for event stream connections and event payloads
• Adds a separate event-streams.yaml (OAS 3.2.0) documenting the text/event-stream + itemSchema event format, while keeping the main openapi.yaml at OAS 3.1.0 with full spectral linting

Notes

• The eventStream schema enforces mutual exclusivity between url and endpoint using oneOf + not clauses
• endpoint provides a structured requestUri (required) and optional origin for proxied deployments that need to override the origin while preserving the request target; if origin is absent, providers use their configured OFREP base URL
• Query parameter descriptions use generic "event stream" / "change notification" language rather than SSE-specific terms, since eventStreams is designed to be extensible beyond SSE
• The main spec stays at OAS 3.1.0 with oas3-schema linting re-enabled; the OAS 3.2.0 text/event-stream + itemSchema representation lives in service/event-streams.yaml

Related Issues

• Implements: ADR-0008
• Relates to: docs: add ADR for SSE bulk evaluation change notifications #63

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the OpenFeature Remote Evaluation Protocol (OFREP) by integrating event stream support, aligning with ADR-0008. It updates the OpenAPI specification to version 3.2.0 and the OFREP version to 0.3.0, enabling real-time change notifications for flag configurations. This allows providers to subscribe to event streams for immediate updates, moving beyond traditional polling mechanisms for detecting changes.

Highlights

• ADR-0008 Implementation: Implemented event stream support in the OpenAPI specification as defined in ADR-0008, enabling real-time change notifications for flag configurations.
• OpenAPI Version Update: Updated the OpenAPI specification version from 3.1.0 to 3.2.0 to support text/event-stream and itemSchema.
• OFREP Version Bump: Bumped the OpenFeature Remote Evaluation Protocol (OFREP) version from 0.2.0 to 0.3.0.
• Event Stream Integration: Introduced an eventStreams property to both single and bulk evaluation success responses, providing connection details for change notifications.
• New Query Parameters: Added flagConfigEtag and flagConfigLastModified query parameters to evaluation endpoints, allowing for change-triggered re-fetches with cache validation metadata.
• New Schemas Defined: Defined new schemas for event stream connections (eventStream, eventStreamEndpoint) and Server-Sent Event (SSE) payloads (sseEvent, sseEventData).
• Webhook Documentation: Included a webhook definition for flagConfigChanged to document the text/event-stream content type using OAS 3.2.0 conventions.
• Spectral Rule Disabled: Disabled the oas3-schema rule in .spectral.yaml due to current Spectral limitations with OpenAPI 3.2.0 support.

Changelog

• .spectral.yaml
  • Disabled oas3-schema rule.
• service/openapi.yaml
  • Updated OpenAPI version from 3.1.0 to 3.2.0.
  • Updated OFREP version from 0.2.0 to 0.3.0.
  • Added flagConfigEtag query parameter to /evaluate endpoint.
  • Added flagConfigLastModified query parameter to /evaluate endpoint.
  • Added eventStreams property to the successful evaluation response example for /evaluate.
  • Added flagConfigEtag query parameter to /evaluate/batch endpoint.
  • Added flagConfigLastModified query parameter to /evaluate/batch endpoint.
  • Added eventStreams property to the successful bulk evaluation response example for /evaluate/batch.
  • Introduced webhooks section with flagConfigChanged for SSE documentation.
  • Added eventStreams property to bulkEvaluationSuccess schema.
  • Added eventStreams property to serverEvaluationSuccess schema.
  • Defined new eventStream schema, including type, url, endpoint, and inactivityDelaySec properties, with oneOf for url or endpoint.
  • Defined new eventStreamEndpoint schema with origin and requestUri.
  • Defined new sseEvent schema for Server-Sent Events, including data, event, id, and retry.
  • Defined new sseEventData schema for SSE event payloads, including type, etag, and lastModified.

Activity

• No human activity (comments, reviews, etc.) has occurred on this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request successfully implements ADR-0008 by adding event stream support to the OpenAPI specification. The changes are well-structured, including the version bump to OpenAPI 3.2.0, the addition of new schemas for event streams, and new query parameters. My review includes a few suggestions to enhance maintainability and schema precision by reducing parameter duplication and adding more specific constraints to the new schemas.

I am having trouble creating individual review comments. Click here to see my feedback.

service/openapi.yaml (57-90)

To improve maintainability and reduce duplication, consider defining the flagConfigEtag and flagConfigLastModified parameters as reusable components under components.parameters. You can then reference them in both the /ofrep/v1/evaluate/flags/{key} and /ofrep/v1/evaluate/flags paths using $ref. This ensures consistency and simplifies future updates.

service/openapi.yaml (453-459)

The description states that currently only sse is a defined type. To make the schema more precise and self-documenting for the current version, consider constraining this field to the known value using enum.

        type:
          type: string
          enum: ["sse"]
          description: |
            The connection type identifying the push mechanism to use.
            Currently only `sse` is defined. Providers must ignore entries
            with unknown types for forward compatibility.
          example: "sse"

service/openapi.yaml (474-485)

The description mentions that providers should default to 120 seconds for inactivityDelaySec if the value is not present. It's a good practice to explicitly define this default in the schema using the default keyword. This makes the API contract clearer for consumers.

        inactivityDelaySec:
          type: integer
          minimum: 1
          default: 120
          description: |
            Number of seconds of client inactivity (e.g., browser tab hidden,
            mobile app backgrounded) after which the connection should be closed
            to conserve resources. The client must reconnect and perform a full
            unconditional re-fetch when activity resumes. When determining the
            effective inactivity timeout, providers should use a client-side
            override if configured; otherwise use this value when present;
            otherwise default to 120 seconds.
          example: 120

service/openapi.yaml (524-529)

The description states that the SSE event type is always message. To enforce this and make the schema more strict, you can add an enum with the single allowed value.

        event:
          type: string
          enum: ["message"]
          description: |
            The SSE event type. Always `message` for OFREP events. Providers
            must inspect `data.type` rather than this field for event routing.
          example: "message"

service/openapi.yaml (550-555)

The description mentions that currently only refetchEvaluation is defined for the event type. To make the schema more precise for this version of the API, you can constrain this field to the known value using enum.

        type:
          type: string
          enum: ["refetchEvaluation"]
          description: |
            The OFREP event type. Currently only `refetchEvaluation` is defined.
            Providers must ignore unknown values for forward compatibility.
          example: "refetchEvaluation"

[jonathannorris]

/gemini review

[gemini-code-assist]

Code Review

This pull request updates the OFREP specification to introduce Server-Sent Events (SSE) for real-time change notifications, primarily for client-side providers using bulk evaluation. Key changes include updating ADR-0008 to reflect this scope, bumping the OpenAPI version to 3.2.0, and adding the necessary schemas, parameters, and webhook definitions for event streams. Review feedback suggests adding a comment to explain the use of the non-standard OpenAPI 3.2.0 version for better maintainability and simplifying ETag examples by removing unnecessary double quotes to improve clarity for implementers.

[Copilot]

Pull request overview

Implements ADR-0008’s event stream (SSE) change-notification support in the OFREP OpenAPI spec for the bulk evaluation endpoint, including new schemas and request metadata for change-triggered re-fetches.

Changes:

• Bump OpenAPI version to 3.2.0 and OFREP version to 0.3.0.
• Add eventStreams to the bulk evaluation success response plus new eventStream / SSE event payload schemas and a text/event-stream webhook description.
• Add flagConfigEtag / flagConfigLastModified query parameters for change-triggered bulk re-fetches; adjust Spectral rules to accommodate OAS 3.2.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.

File	Description
service/openapi.yaml	Adds bulk-eval event stream support (schemas + response field + query params) and documents SSE stream format; bumps OpenAPI/OFREP versions.
service/adrs/0008-sse-for-bulk-evaluation-changes.md	Aligns ADR scope to client-side bulk evaluation only and updates the documented schema additions accordingly.
.spectral.yaml	Disables a Spectral rule due to lack of OpenAPI 3.2 support.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[toddbaert]

Minor nit; looks great overall.

[toddbaert]

Approved, minor nit: #67 (comment)

[jonathannorris]

@lukas-reining / @thomaspoignant / @erka any further comments on this one?

[lukas-reining]

Looks good so far, left some feedback.

[jonathannorris]

/gemini review

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[gemini-code-assist]

Code Review

This pull request updates the SSE ADR and OpenAPI specification to scope real-time change notifications to static-context providers. It bumps the OpenAPI version to 3.2.0, introduces SSE-related schemas and parameters, and temporarily disables a Spectral rule. Feedback was provided to ensure ETag examples remain quoted to comply with RFC 7232.

[jonathannorris]

Split the spec into two files to keep the main openapi.yaml at OAS 3.1.0 with full spectral linting while still documenting the SSE event format using OAS 3.2.0's text/event-stream + itemSchema support:

• service/openapi.yaml (3.1.0) — core OFREP spec with all schemas including sseEvent / sseEventData
• service/event-streams.yaml (3.2.0) — supplementary file documenting the SSE event stream format via components/pathItems, referencing the schemas in the main spec

[lukas-reining]

Looks good to me, thanks @jonathannorris!