Skip to content

Name the wiki spec as the API source of truth - #1844

Merged
Ahmedhossamdev merged 4 commits into
OneBusAway:mainfrom
chikolavosaki-sys:docs/1692-wiki-source-of-truth
Nov 2, 2026
Merged

Ahmedhossamdev merged 4 commits into
OneBusAway:mainfrom
chikolavosaki-sys:docs/1692-wiki-source-of-truth

Conversation

@chikolavosaki-sys

@chikolavosaki-sys chikolavosaki-sys commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #1692

What it does

Rewrites the REST API Documentation section of CLAUDE.md so the maglev.wiki spec is the source of truth and openapi.yml comes second, as suggested in #1692. Also points step 1 of the New Endpoint Implementation Workflow at the wiki instead of the legacy API docs. Docs only.

Root cause

CLAUDE.md said every endpoint "MUST behave identically" to openapi.yml and that "the spec wins". openapi.yml has known errors: its trips-for-route entry says includeStatus and includeSchedule default to false (testdata/openapi.yml:613, :619), while Java and the wiki use true. Following the old rule produced PRs such as #1336 and #1649, which were closed for that reason. The rule also conflicted with the PR template's checklist item for endpoints outside the SDK.

The new text:

  • names the wiki as authoritative, matching Java unless an Implementation Decisions section records a difference
  • ranks openapi.yml second, with the trips-for-route example
  • says disagreements are raised on OneBusAway/sdk-config rather than "fixed" in Maglev
  • notes that endpoints outside the SDK need no openapi.yml entry if the PR says why, matching the PR template

Testing

  • Test failing on main before this change: n/a (documentation only)
  • Manual check: Confirmed the openapi.yml defaults quoted above and that the wiki is at https://github.com/OneBusAway/maglev/wiki. go vet (both tag sets), make test and go fmt ./... pass.

Checklist

Ready-for-review requirement: Every box must be checked. If any statement is not true, keep the pull request
as Draft.

  • This PR addresses one issue.
  • It is under ~200 changed lines, or the description says why it can't be split.
  • This PR is not a bug fix, or the new or changed test fails on main and passes on this branch.
  • Each commit is one logical change with a clear message.
  • I did not hand-edit sqlc-generated files under gtfsdb/ (db.go, models.go, query.sql.go) or testdata/openapi.yml (synced from upstream).
  • This PR changes no handler, or handlers pass r.Context() to DB/service calls, not context.Background().
  • The response comparison above is filled in, or this PR doesn't change a Java-served response.
  • This PR adds no endpoint, or each new endpoint matches testdata/openapi.yml, has an issue open on OneBusAway/sdk-config, or is outside the SDK and the description says why.
  • I read every line of this diff and can explain it if asked.

Notes for reviewers (optional)

Summary by CodeRabbit

  • Documentation
    • REST API guidance now identifies the endpoint’s maglev.wiki page and Implementation Decisions as the primary references for endpoint behavior, with OpenAPI as a secondary source.
    • When the wiki and OpenAPI disagree, the guidance directs developers to follow the wiki and report the discrepancy.
    • Guidance clarifies that endpoints outside the SDK do not need an OpenAPI entry, but their pull request description should explain why.
    • Legacy API documentation remains available as a reference.

CLAUDE.md said every endpoint must behave identically to openapi.yml
and that the spec wins. The maglev.wiki spec is authoritative in
practice, and openapi.yml has known errors: it says trips-for-route's
includeStatus and includeSchedule default to false, where Java and the
wiki say true. Following the old rule led to PRs that were rejected
for that reason.

Make the wiki the source of truth, rank openapi.yml second, and say
that disagreements go to OneBusAway/sdk-config. Mention endpoints
outside the SDK, matching the PR template. Point the new-endpoint
workflow at the wiki instead of the legacy API docs.
Copilot AI balanced review requested due to automatic review settings October 26, 2026 15:08
@coderabbitai

coderabbitai Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Caution

Review failed

The pull request is closed.

No actionable comments were generated in the recent review.

Recent review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Repository UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: ff337f5d-3bd3-4a11-9ab0-db016c8eecaf
Commits

Reviewing files that changed from the base of the PR and between 138ddad and 345d22c.

Files selected for processing: 1
  • CLAUDE.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Walkthrough

CLAUDE.md now directs endpoint research to the maglev.wiki page and its Implementation Decisions. It makes the wiki authoritative for endpoint behavior, describes OpenAPI as secondary, and explains how to report discrepancies and document endpoints outside the SDK.

Changes: Endpoint guidance

Layer / File(s) Summary
Research workflow and API source guidance
CLAUDE.md
The research instructions point developers to endpoint wiki pages and Implementation Decisions. The REST API guidance makes the wiki authoritative, treats OpenAPI as secondary, directs discrepancies to OneBusAway/sdk-config, and allows endpoints outside the SDK without an OpenAPI entry when the PR description explains why. The legacy API documentation remains as a reference.

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

Change: Other · Severity of issue fixed: Medium

Possibly related issues

  • OneBusAway/maglev#1710 — The issue concerns documenting endpoint behavior and Java differences in the wiki; this change makes the wiki the source of truth.
  • OneBusAway/maglev#1727 — The issue concerns missing endpoint wiki pages and Implementation Decisions; this change directs contributors to those pages and decisions.
  • OneBusAway/maglev#1825 — The issue concerns wiki and OpenAPI disagreements and the sdk-config update path; this change defines that source precedence and discrepancy workflow.
  • OneBusAway/maglev#1499 — The issue concerns Java-versus-Maglev parameter behavior and documenting deviations in Implementation Decisions; this change refers contributors to those decisions.

Possibly related PRs

  • OneBusAway/maglev#1755 — It adds endpoint specification documents and maps them to wiki pages, which this change uses for endpoint research and behavior guidance.

Suggested reviewers: aaronbrethorst

Merge Risk: Minimal · previous review 345d2

No actionable merge-blocking issue was found.

Pre-merge checks: Passed 5
Check name Status Explanation
Title check Passed The title clearly and concisely identifies the main change: making the wiki specification the API source of truth.
Description check Passed The description follows the repository template, explains the change and root cause, reports testing, and completes the checklist. The response comparison section is not needed because this is a docum…
Linked Issues check Passed Issue #1692 has no coding requirements. It asks only for documentation changes in CLAUDE.md, and the diff changes only CLAUDE.md. The diff (merge base 138ddad to head 345d22c, CLAUDE.md only) meets ea…
Out of Scope Changes check Passed The diff has two hunks, both in CLAUDE.md. The first hunk changes step 1 of the New Endpoint Implementation Workflow to point at the wiki page instead of the legacy API docs. The second hunk rewrites …
Docstring Coverage Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Full details: Description check

Explanation

The description follows the repository template, explains the change and root cause, reports testing, and completes the checklist. The response comparison section is not needed because this is a documentation-only change.

Full details: Linked Issues check

Explanation

Issue #1692 has no coding requirements. It asks only for documentation changes in CLAUDE.md, and the diff changes only CLAUDE.md. The diff (merge base 138ddad to head 345d22c, CLAUDE.md only) meets each requested change:

  • Wiki as source of truth: the REST API Documentation section names the maglev.wiki spec as authoritative for endpoint behavior. It states that Maglev matches Java unless the page's Implementation Decisions section records a difference.
  • openapi.yml second: the section ranks testdata/openapi.yml second and gives the trips-for-route includeStatus/includeSchedule example.
  • Disagreements raised upstream: the text says to follow the wiki, raise the discrepancy on OneBusAway/sdk-config, and not change Maglev to match openapi.yml.
  • Maglev-only endpoints: the text says endpoints outside the SDK (such as /api/ondemand) need no openapi.yml entry if the PR description explains why.
    The openapi.yml default values cited in the text were not re-verified in this review. The file read was truncated before the cited lines. This does not affect the verdict, because the claim is explanatory text and the issue states the same defaults.
Full details: Out of Scope Changes check

Explanation

The diff has two hunks, both in CLAUDE.md. The first hunk changes step 1 of the New Endpoint Implementation Workflow to point at the wiki page instead of the legacy API docs. The second hunk rewrites the REST API Documentation section, which the linked issue targets. The workflow change is not listed in #1692. It applies the same source-of-truth rule within the same file, and without it the workflow would still send endpoint research to the legacy docs first. The legacy URL is kept as a reference in the REST API section. No unrelated code, configuration, or test changes appear in the diff. The change is documentation only, consistent with the PR description.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown

The description follows the PR template.

@github-actions github-actions Bot added the follows-template The PR description follows the PR template label Oct 26, 2026
@CLAassistant

CLAassistant commented Oct 26, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@Ahmedhossamdev Ahmedhossamdev left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@chikolavosaki-sys thanks, this is a clear rewrite and the trips-for-route example checks out against Java and the wiki. Looks good to me. Two small wording points inline: the /api/ondemand example isn't on main yet, and the text doesn't say what to do when an endpoint has no wiki page. Either can be a follow-up.

Comment thread CLAUDE.md Outdated
The OpenAPI spec (`testdata/openapi.yml`, synced from [OneBusAway/sdk-config](https://github.com/OneBusAway/sdk-config/blob/main/stainless/openapi.yml)) comes second. It generates the client SDKs and has known errors. For example, it gives trips-for-route's `includeStatus` and `includeSchedule` a default of `false`, where Java and the wiki use `true`.

**All API endpoints MUST behave identically to what is defined in this OpenAPI spec.** This is the single source of truth for request parameters, response schemas, field names, types, and status codes. Always fetch the latest version of this spec before implementing new endpoints or modifying existing ones. If the codebase diverges from the spec, the spec wins.
When the wiki and openapi.yml disagree, follow the wiki and raise the discrepancy on OneBusAway/sdk-config. Don't change Maglev's behavior to match openapi.yml. An endpoint outside the SDK (such as `/api/ondemand`) needs no openapi.yml entry, but the PR description must say why.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/api/ondemand only exists in the open GTFS-Flex PRs (#1481 to #1485), so an agent grepping for it finds nothing. Could this use an endpoint already on main? /api/where/metrics.json or problem-reports-for-trip are Maglev-only and not in openapi.yml.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh yah.. , switched the example to /api/where/metrics.json.

Comment thread CLAUDE.md
## REST API Documentation

The official REST API documentation is available at: https://developer.onebusaway.org/api/where/methods
**The [maglev.wiki](https://github.com/OneBusAway/maglev/wiki) spec is the source of truth for endpoint behavior**: request parameters, defaults, response fields and status codes. Each endpoint page describes the Java OneBusAway server's behavior, which Maglev matches unless the page's Implementation Decisions section records a deliberate difference.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some endpoints have no wiki page yet (block, report-problem-with-trip/stop, problem-reports-for-trip/stop), and neither will a new one. Could this add a fallback, e.g. "If the endpoint has no wiki page, follow the Java implementation and flag it in the PR"? Otherwise an agent may fall back to treating openapi.yml as the authority.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok so I added a fallback if an endpoint has no wiki page, follow the Java implementation, not openapi.yml, and flag it in the PR.

Some endpoints, such as block and the report-problem endpoints, have
no wiki page yet. Without a fallback, an agent may treat openapi.yml
as the authority for them; say to follow the Java implementation and
flag it in the PR instead.

Use /api/where/metrics.json as the example of an endpoint outside the
SDK. /api/ondemand only exists in open GTFS-Flex PRs, so it can't be
found on main.

@Ahmedhossamdev Ahmedhossamdev left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sonarqubecloud

sonarqubecloud Bot commented Nov 2, 2026

Copy link
Copy Markdown

@Ahmedhossamdev
Ahmedhossamdev merged commit 2a2bcea into OneBusAway:main Nov 2, 2026
11 of 12 checks passed
@aaronbrethorst aaronbrethorst mentioned this pull request Nov 2, 2026
9 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

follows-template The PR description follows the PR template

Projects

None yet

Development

Successfully merging this pull request may close these issues.

CLAUDE.md should name the wiki spec as the source of truth, not openapi.yml

4 participants