Document session JSONL schema stability for external integrations

Open 💬 4 comments Opened May 4, 2026 by sanyathoque

💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

What feature would you like to see?

A docs page that defines which session JSONL fields/events are stable for external tooling and which are internal/subject to change.

Problem

External integrations (dashboards, wrappers, review surfaces, CI helpers) consume Codex session JSONL, but there is no explicit stability contract. This forces parsers to depend on implementation details and breaks across updates.

Proposal

Add a docs section (for example docs/session-jsonl.md) that includes:

Event envelope shape and required top-level fields.
Event type catalog currently emitted in session JSONL.
Stability level for each field:

stable for external use
experimental
internal

Versioning guidance:

how additions/removals are communicated
how external parsers should handle unknown fields/events

One or two realistic examples from interactive and codex exec runs.

Why this helps

Lowers friction for community integrations without requiring new runtime features.
Reduces duplicate "parser broke" issues.
Creates a clear foundation for future lifecycle APIs/events.

Acceptance criteria

Docs explicitly define a stability contract for session JSONL fields.
Docs list at least one canonical sample per run mode (interactive and exec).
Docs include forward-compat parser guidance (ignore unknown fields, branch by version when present).
Changelog/release notes point to this contract when format-affecting changes ship.

Scope note

This request is docs-first and additive. It does not require changing current JSONL emission behavior.

View original on GitHub ↗

4 Comments

github-actions[bot] contributor · 3 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

#20943

Powered by Codex Action

etraut-openai contributor · 3 months ago

I don't think we're prepared to treat this as a documented, stable contract at this time. We will endeavor not to make unnecessary changes, but you should expect to see this schema to continue to evolve.

We are treating the app server interface as a durable, stable, and fully-documented API. I don't know if that interface works for your use case, but if you're concerned about long-term interface stability, that might be a better option for you.

sanyathoque · 3 months ago

Thanks for the clarification — this is helpful direction.

I’ll treat session JSONL as internal/evolving and move integration proposals toward the app-server interface when long-term stability is required.

If useful, I can open or draft a docs-only follow-up that explicitly guides external integrators to prefer app-server over session JSONL for stable client integrations.

Herrtian · 3 months ago

The maintainer direction above makes sense to me: documenting rollout JSONL as a stable schema would probably over-promise. I prepared a smaller follow-up branch that takes the opposite approach and documents the boundary instead:

https://github.com/Herrtian/codex/tree/docs/rollout-jsonl-stability-note

The branch adds a short note to codex-rs/thread-store/README.md saying:

local rollout JSONL is a storage format, not a stable external API;
durable external integrations should prefer the codex app-server protocol;
local-only rollout readers should tolerate unknown fields/item types and validate the Codex version they target.

Validation I ran:

git diff --check -- codex-rs/thread-store/README.md

PR creation appears to be limited by the repo's invitation-only contribution policy, so I'm leaving the branch here. If this is useful as a docs-only clarification, could a maintainer invite a PR or pick it up internally?