Skip to content

[good first issue] Add a schema reference page to docs/ #2

Closed

Description

@atomize-lab

Summary

Create a single-page reference (docs/schema-reference.md) that lists every field in tweet.json v1, the agent bundle v1.0, and the manifest v1.0, with type, required/optional status, and a one-line description.

Context

Currently, field definitions are spread across three docs:

  • docs/agent-bundle-spec.md (bundle fields)
  • docs/provenance.md (manifest fields)
  • Inline in tools/scripts/tweet_schema.py (tweet.json fields)

A consolidated reference page helps both human contributors and AI agents quickly look up any field without reading multiple documents.

What needs to be done

  • Read tools/scripts/tweet_schema.py to extract all tweet.json fields
  • Read docs/agent-bundle-spec.md section 3 for bundle fields
  • Read docs/provenance.md section 2 for manifest fields
  • Create docs/schema-reference.md with three tables (one per schema), columns: Field | Type | Required | Description
  • Add a link to the new page in README.md documentation table
  • Verify all field names match the actual JSON Schema files in schemas/

Skills helpful

  • Markdown
  • JSON (reading schema files)

No coding experience required -- this is a documentation task.

How to verify

# Ensure the doc renders and links are valid
python -c "from pathlib import Path; p=Path('docs/schema-reference.md'); print('exists:', p.exists(), 'size:', p.stat().st_size)"

# Verify schema field names match
cd tools && python citeseal.py lint && cd ..

Checklist

  • This task does not involve bulk-scraping or bypassing platform access controls.
  • I have checked existing issues for duplicates.

Activity

  1. atomize-lab commented on Jul 20, 2026

    @atomize-lab
    OwnerAuthor

    Maintenance update: PR #7 was closed after the requested schema corrections and acceptance items remained unresolved. Issue #2 is still open, unassigned, and available for a fresh /claim.

    A replacement should rebuild all three tables directly from the repository schemas, add the required README documentation-table link, and fold in #12's copy-pasteable minimum tweet.json example. Please claim #2 before opening a replacement PR so this remains one issue with one authoritative implementation.

  2. aryansk commented on Aug 9, 2026

    @aryansk
    Contributor

    /claim

  3. atomize-lab commented on Aug 9, 2026

    @atomize-lab
    OwnerAuthor

    Assigned to @aryansk based on the valid /claim. PR #17 is now the single authoritative implementation for #2; please continue iterating there rather than opening a parallel PR.

    Reminder: #12 is part of #2's documentation acceptance criteria, so the final schema reference must include a copy-pasteable minimum tweet.json example.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationgood first issueGood for newcomershelp wantedExtra attention is needed

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions