feat: Check request body fields against OpenAPI by gmlewis · Pull Request #4576 · google/go-github

gmlewis · 2026-09-18T14:45:55Z

Checking new PRs against the official GitHub v3 API for required fields in body parameters is extremely time-consuming, monotonous, and error-prone. This new tool helps contributors and maintainers alike by automating the mechanically-verifiable parts.

This PR adds tools/schemafields, run by script/check-schema-fields.sh and wired into script/lint.sh and the linter workflow. It checks each request body struct field against the request body schema of the operations that send it, mapping structs to operations via the //meta:operation annotation and the by-value body parameter that paramcheck requires, so new endpoints are covered with no new annotation.

No breaking API changes are made in this PR, but an upcoming PR will -fix the problems found.

AI assistance was used to write this PR.

Supersedes #4375 (closed), which required a //meta:schema annotation on every struct.
Relates to #3644 and #4023, and to the required-but-omittable bugs in #3336, #3226 and #2909.

cc: @stevehipwell - @Not-Dhananjay-Mishra

Signed-off-by: Glenn Lewis <6598971+gmlewis@users.noreply.github.com>

codecov · 2026-09-18T14:50:28Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.59%. Comparing base (8d9197f) to head (97e80e9).
⚠️ Report is 2 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #4576   +/-   ##
=======================================
  Coverage   98.59%   98.59%           
=======================================
  Files         197      197           
  Lines       18326    18326           
=======================================
  Hits        18068    18068           
  Misses        258      258

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Signed-off-by: Glenn Lewis <6598971+gmlewis@users.noreply.github.com>

Not-Dhananjay-Mishra · 2026-09-19T12:08:23Z

Can we use .yml/.yaml file instead of .txt

The file is a flat one-key-per-line list plus a comment header that the tool preserves verbatim when it rewrites the file. YAML buys nothing here but costs a parser dependency (the module currently requires only go-cmp) and comment round-tripping (yaml.v3 drops comments, so -fix/-write-exceptions would lose the header). If the format ever needs per-entry metadata, we can change it. But for now, txt is the better choice, IMO.

Signed-off-by: Glenn Lewis <6598971+gmlewis@users.noreply.github.com>

gmlewis · 2026-09-19T14:00:58Z

@Not-Dhananjay-Mishra - thank you for the review! I addressed two of your comments, and pushed back on the other two 😄. PTAL.

Not-Dhananjay-Mishra · 2026-09-19T15:52:29Z

+	case f.isStruct:
+		// CONTRIBUTING.md prefers omitzero over a pointer for structs, and it is the
+		// only omit option that works on a struct value.
+		c.add(&diagnostic{
+			sev: sevWarn, rule: ruleOptionalValueType, file: f.file, line: f.line,
+			owner: si.name, field: f.goName, info: f, action: &fixAction{addOmit: "omitzero"},
+			message: fmt.Sprintf("%q is optional in the schema, but the Go field is a value type, so it is always sent: add omitzero", f.jsonName),
+		})


I think our structfield linter will not allow this kind of case, where a non-pointer struct uses omitzero.

type SomeRequest struct { OptionalStruct Struct `json:"optional_struct,omitzero"` }

I think the reason that all tests pass is because our linters are guarded by the "github" package name.

I think the reason that all tests pass is because our linters are guarded by the "github" package name.

linters are not running inside testdata/... so that why linter didn't caught it.

tools/schemafields/testdata/golden/TestFix/github/runner_groups.go

// StructTypeRequest has an optional property of a struct value type. type StructTypeRequest struct { // Inner is optional and CONTRIBUTING.md asks for omitzero on structs. Inner InnerConfig `json:"inner,omitzero"` }

I moved it outside temporary to test it, and linters start complaning.

tools/schemafields/runner_groups.go:23:2: change the "ResponseOnly" field type to "*string" in the struct "CreateRunnerGroupRequest" because its json tag uses "omitempty" (structfield) ResponseOnly string `json:"response_only,omitempty"` ^ tools/schemafields/runner_groups.go:47:2: change the "Inner" field type to "*InnerConfig" in the struct "StructTypeRequest" (structfield) Inner InnerConfig `json:"inner,omitzero"`

I believe that we should suggest %q is optional in the schema, but the Go field is a value type, so it is always sent: use pointer with omitempty

You are absolutely right, @Not-Dhananjay-Mishra!

I believe this is now fixed and I removed the 19 false-positives that were caused by this error.

PTAL.

Signed-off-by: Glenn Lewis <6598971+gmlewis@users.noreply.github.com>

Not-Dhananjay-Mishra · 2026-09-20T14:54:42Z

+
+  print_header "Checking request body fields against the OpenAPI schemas"
+  if script/check-schema-fields.sh; then
+    printf "${GREEN}✔ request body fields match the OpenAPI schemas${NC}\n"
+  else
+    printf "${RED}✘ request body fields disagree with the OpenAPI schemas${NC}\n"
+    fail
+  fi


When running script/lint.sh locally, this doesn't get triggered because it requires the CHECK_GITHUB_OPENAPI=1 environment variable. Is this intentional?

Good call! I've removed it.

Not-Dhananjay-Mishra · 2026-09-20T15:03:56Z

+The `tools/schemafields` package checks Go request body struct field
+optionality against GitHub's OpenAPI request body schemas. It is run by
+`script/check-schema-fields.sh`, which `script/lint.sh` and the `linter`
+workflow call, so you rarely need to run it directly.


I feel that this statement

It is run by
script/check-schema-fields.sh, which script/lint.sh and the linter
workflow call, so you rarely need to run it directly.

feels inconsistent since contributors need to set the environment variable first then only they can run script/check-schema-fields.sh via script/lint.sh.

Agreed. Updated.

Not-Dhananjay-Mishra

Just one small doubt. Otherwise, LGTM 🫠

Signed-off-by: Glenn Lewis <6598971+gmlewis@users.noreply.github.com>

gmlewis · 2026-09-20T18:04:43Z

Updated. Thank you, @Not-Dhananjay-Mishra!

feat: Add new schemafields tool

87021d6

Signed-off-by: Glenn Lewis <6598971+gmlewis@users.noreply.github.com>

gmlewis added the NeedsReview PR is awaiting a review before merging. label Sep 18, 2026

Fix Windows breakages

ab76498

Signed-off-by: Glenn Lewis <6598971+gmlewis@users.noreply.github.com>

Not-Dhananjay-Mishra reviewed Sep 19, 2026

View reviewed changes

Address review feedback

07cad08

Signed-off-by: Glenn Lewis <6598971+gmlewis@users.noreply.github.com>

Not-Dhananjay-Mishra reviewed Sep 19, 2026

View reviewed changes

Address review feedback

5f1ca55

Signed-off-by: Glenn Lewis <6598971+gmlewis@users.noreply.github.com>

Not-Dhananjay-Mishra reviewed Sep 20, 2026

View reviewed changes

Not-Dhananjay-Mishra approved these changes Sep 20, 2026

View reviewed changes

Remove CHECK_GITHUB_OPENAPI env var

97e80e9

Signed-off-by: Glenn Lewis <6598971+gmlewis@users.noreply.github.com>

gmlewis merged commit f88a6d1 into google:master Sep 20, 2026
15 checks passed

gmlewis deleted the schemafields branch September 20, 2026 18:18

gmlewis removed the NeedsReview PR is awaiting a review before merging. label Sep 20, 2026

This was referenced Sep 20, 2026

chore: Update maintenance tooling #4580

Merged

fix!: Match request body fields to the OpenAPI schemas #4581

Open

Conversation

gmlewis commented Sep 18, 2026

Uh oh!

codecov Bot commented Sep 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gmlewis commented Sep 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Not-Dhananjay-Mishra Sep 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gmlewis Sep 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Not-Dhananjay-Mishra left a comment

Choose a reason for hiding this comment

Uh oh!

gmlewis commented Sep 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov Bot commented Sep 18, 2026 •

edited

Loading

Not-Dhananjay-Mishra Sep 20, 2026 •

edited

Loading

gmlewis Sep 20, 2026 •

edited

Loading