Repository navigation
Document session JSONL schema stability for external integrations #20952
Description
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 execruns.
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.
Activity
github-actions commentedon May 4, 2026
Potential duplicates detected. Please review them and close your issue if it is a duplicate.
Powered by Codex Action
etraut-openai commentedon May 4, 2026
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 commentedon May 5, 2026
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 commentedon May 22, 2026
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.mdsaying:codex app-serverprotocol;Validation I ran:
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?