docs: Amend ADR-0008 to adjust the SSE wire format to allow for customized formatting

[JamieSinn]

This PR

In cases where there's different object formats (Ably) the default format will conflict and not be valid/acted on by SDKs. This resolves that and ensures that providers can implement their own wrapping/deserialization as long as it returns the correct format to the parsed data.

For example, this also allows for varying date formats for the lastModified values.

Related Issues

open-feature/js-sdk-contrib#1583

[coderabbitai]

📝 Walkthrough

Walkthrough

The ADR changes SSE data handling to customizable parsing, clarifies that event types come from the parsed sseEvent.type, and documents optional provider overrides for wrapped or re-encoded vendor payloads.

Changes

SSE payload parsing contract

Layer / File(s)	Summary
Customizable SSE parsing guidance service/adrs/0008-sse-for-bulk-evaluation-changes.md	The ADR defines JSON parsing as the default for string data, preserves non-string data, requires reading sseEvent.type, and documents optional overrides for extracting OFREP events from wrapped payloads.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Suggested reviewers: toddbaert, jonathannorris

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the ADR update to relax SSE wire-format assumptions for customizable provider formatting.
Description check	✅ Passed	The description is clearly related to the SSE formatting and deserialization changes described in the PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[toddbaert]

nit: https://github.com/open-feature/protocol/pull/82/changes#r3615615699

[jonathannorris]

Just update the title to docs: instead of feat:

[lukas-reining]

This is a good addition.
Initially I was worried that this could open the gates for many custom implementations that can become hard to get together later but I think the way it is specified does not have this problem.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

service/adrs/0008-sse-for-bulk-evaluation-changes.md (1)

74-94: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Define the canonical parser output and preserve the OpenAPI contract.

The text alternates between a parsed sseEvent and a parsed OFREP event object. However, service/openapi.yaml:442-503 defines type, etag, and lastModified on sseEventData, nested under the envelope’s data. Clarify that custom adapters must transform vendor-specific messages into the canonical sseEventData shape (and normalize lastModified to Unix seconds or ISO 8601) before these fields are read; otherwise providers may implement incompatible field paths or forward unsupported date formats.

Proposed wording direction

- Providers must inspect the `type` field on the parsed sseEvent message
+ Providers must inspect the `type` field on the canonical parsed sseEventData payload

- returns the parsed OFREP event object
+ returns the canonical sseEventData object, including supported field types

- before `type` / `etag` / `lastModified` are read
+ before `type` / `etag` / `lastModified` are read; adapters must normalize
+ `lastModified` to Unix seconds or an ISO 8601 date-time string

Also applies to: 165-165

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@service/adrs/0008-sse-for-bulk-evaluation-changes.md` around lines 74 - 94,
Clarify the SSE parsing documentation so the canonical parser output is the
OpenAPI sseEventData object nested under the sseEvent envelope’s data field,
rather than an unspecified parsed OFREP event object. State that custom adapters
must map vendor-specific payloads to this shape before providers read type,
etag, or lastModified, and normalize lastModified to Unix seconds or ISO 8601.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@service/adrs/0008-sse-for-bulk-evaluation-changes.md`:
- Around line 74-94: Clarify the SSE parsing documentation so the canonical
parser output is the OpenAPI sseEventData object nested under the sseEvent
envelope’s data field, rather than an unspecified parsed OFREP event object.
State that custom adapters must map vendor-specific payloads to this shape
before providers read type, etag, or lastModified, and normalize lastModified to
Unix seconds or ISO 8601.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 248efdc6-ba20-4e14-a059-aedb05f877e2

📥 Commits

Reviewing files that changed from the base of the PR and between 7d1c3dc and 02b34bd.

📒 Files selected for processing (1)

• service/adrs/0008-sse-for-bulk-evaluation-changes.md

[lukas-reining]

Looks good to me!