Skip to content

docs: draft parsed result ZIP contract RFC - #420

Open
Frankie-Xu wants to merge 1 commit into
Ontos-AI:mainfrom
Frankie-Xu:docs/Frankie-Xu/parsed-result-contract-rfc
Open

Frankie-Xu wants to merge 1 commit into
Ontos-AI:mainfrom
Frankie-Xu:docs/Frankie-Xu/parsed-result-contract-rfc

Conversation

@Frankie-Xu

@Frankie-Xu Frankie-Xu commented Sep 14, 2026

Copy link
Copy Markdown

Related to #45. RFC only — no models, validator, or worker change.

Summary

  • Add docs/design/parsed-result-contract.md, a draft contract for the parse-result ZIP (chunks.json, doc_nav.json, manifest.json).
  • Answers nuemaan's three scope questions from 2026-06-12 (schema location, hard-fail vs warn, versioning) against current writers on main @ 9489fa2c.
  • Locks the observed v1 shape, including chunk_type=page and table content as an asset path, which AGENTS.md does not fully describe.
  • Asks maintainers to confirm five decisions on Parsed result contract #45 before any implementation PR.

Verification

  • Docs-only. No Python change.
  • Rechecked writers: zip_package_writer.py, zip_result_service.py, zip_chunk_schema.py, zip_doc_navigation.py, zip_manifest_schema.py, finalize_parse_success.
  • test_parse_task_contract.py still only asserts file presence + counts; this RFC does not extend it.

Deployment Notes

  • No environment variables, migrations, or runtime change
  • Rollback is reverting this PR

Checklist

  • Tests were added or updated when behavior changed — N/A (RFC only)
  • Public docs, examples, or OpenAPI contracts were updated when needed
  • Database migrations are idempotent and safe to deploy — N/A
  • Logs, errors, and validation paths avoid leaking secrets or user data
  • The pull request description explains any breaking or user-visible change — none; no code

Record maintainer decisions needed for issue Ontos-AI#45 before any
Pydantic models or worker validation land.

Co-authored-by: Frankie-Xu <Frankie-Xu@users.noreply.github.com>
@Frankie-Xu
Frankie-Xu marked this pull request as ready for review September 14, 2026 18:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants