This site hosts the shared documentation that applies to all repositories in the
go-openapi organization.
Rather than duplicating contributing guidelines, coding style, security policies and licensing
across dozens of repositories, we maintain them here as a single source of truth.
Each go-openapi project has its own README and may publish additional project-specific documentation.
The guidelines on this site apply uniformly unless a project’s own documentation states otherwise.
You’ll find here general guidelines to contribute to go-openapi projects.
They mostly correspond to standard practices for open source repositories.
We have tried to keep things as simple as possible.
TL;DR
If you’re an experienced go developer on github, then you should just feel at home with us
and you may well skip the rest of this document.
You’ll essentially apply the usual guidelines for a go library project on github.
These guidelines are common to all libraries published on github by the go-openapi organization,
so you’ll feel at home with any of our projects.
How can I contribute?
There are many ways in which you can contribute, not just code. Here are a few ideas:
Reporting issues or bugs
Suggesting improvements
Documentation
Art work that makes the project look great
Code
proposing bug fixes and new features that are within the main project scope
improving test coverage
addressing code quality issues
Questions & issues
Asking a question
You may inquire anything about this library by reporting a “Question” issue on github.
You may also join our discord server where you may discuss issues or requests.
Reporting issues
Reporting a problem with our libraries is a valuable contribution.
You can do this on the github issues page of the relevant repository.
Please be as specific as possible when describing your issue.
Whenever relevant, please provide information about your environment (go version, OS).
Adding a code snippet to reproduce the issue is great, and a big time saver for maintainers.
Triaging issues
You can help triage issues which may include:
reproducing bug reports
asking for important information, such as version numbers or reproduction instructions
answering questions and sharing your insight in issue comments
Code contributions
Pull requests are always welcome
We are always thrilled to receive pull requests, and we do our best to
process them as fast as possible.
Not sure if that typo is worth a pull request? Do it! We will appreciate it.
If your pull request is not accepted on the first try, don’t be discouraged!
If there’s a problem with the implementation, hopefully you’ve received feedback on what to improve.
If you have a lot of ideas or a lot of issues to solve, try to refrain a bit and post focused
pull requests.
Think that they must be reviewed by a maintainer and it is easy to lose track of things on big PRs.
We’re trying very hard to keep the go-openapi packages lean and focused.
Together, these packages constitute a toolkit for go developers:
it won’t do everything for everybody out of the box,
but everybody can use it to do just about everything related to OpenAPI.
This means that we might decide against incorporating a new feature.
However, there might be a way to implement that feature on top of our libraries.
Environment
You just need a go compiler to be installed. No special tools are needed to work with our libraries.
The minimal go compiler version required is always the old stable (latest minor go version - 1).
Our libraries are designed and tested to work on Linux, MacOS and Windows.
If you’re used to work with go you should already have everything in place.
Although not required, you’ll be certainly more productive with a local installation of golangci-lint,
the meta-linter our CI uses.
If you don’t have it, you may install it like so:
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
Conventions
Git flow
Fork the repo and make changes to your fork in a feature branch.
To submit a pull request, push your branch to your fork (e.g. upstream remote):
github will propose to open a pull request on the original repository.
Typically you’d follow some common naming conventions:
if it’s a bug fixing branch, name it fix/XXX-something where XXX is the number of the
issue on github
if it’s a feature branch, create an enhancement issue to announce your
intentions, and name it feature/XXX-something where XXX is the number of the issue.
NOTE: we don’t enforce naming conventions on branches: it’s your fork after all.
Tests
Submit unit tests for your changes.
Go has a great built-in test framework ; use it!
Take a look at existing tests for inspiration, and run the full test suite on your branch
before submitting a pull request.
Our CI measures test coverage and the test coverage of every patch.
Although not a blocking step - because there are so many special cases -
this is an indicator that maintainers consider when approving a PR.
Please try your best to cover at least 80% of your patch.
Don’t forget to update the documentation when creating or modifying a feature.
Most documentation for our libraries is directly found in code as comments for godoc.
Check your documentation changes for clarity, concision, and correctness.
If you want to assess the rendering of your changes when published to pkg.go.dev, you may
want to install the pkgsite tool proposed by golang.org.
go install golang.org/x/pkgsite/cmd/pkgsite@latest
Then run on the repository folder:
pkgsite .
This will run a godoc server locally where you may see the documentation generated from your local repository.
Commit messages
Pull requests descriptions should be as clear as possible and include a
reference to all the issues that they address.
Pull requests must not contain commits from other users or branches.
Commit messages are not required to follow the “conventional commit” rule, but it’s certainly a good
thing to follow that convention (e.g. “fix: fixed panic in XYZ”, “ci: did this”, “feat: did that” …).
The title in your commit message is used directly to produce our release notes: try to keep them neat.
The commit message body should detail your changes.
If an issue should be closed by a commit, please add this reference in the commit body:
* fixes #{issue number}
Code review
Code review comments may be added to your pull request.
Discuss, then make the suggested modifications and push additional commits to your feature branch.
Be sure to post a comment after pushing. The new commits will show up in the pull
request automatically, but the reviewers will not be notified unless you comment.
Before the pull request is merged,
make sure that you’ve squashed your commits into logical units of work
using git rebase -i and git push -f.
After every commit the test suite should be passing.
Include documentation changes in the same commit so that a revert would remove all traces of the feature or fix.
Sign your work
Software is developed by real people.
The sign-off is a simple line at the end of your commit message,
which certifies that you wrote it or otherwise have the right to
pass it on as an open-source patch.
We require the simple DCO below with an email signing your commit.
PGP-signed commit are greatly appreciated but not required.
Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
660 York Street, Suite 102,
San Francisco, CA 94110 USA
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
Coding Style
Coding style at go-openapi
TL;DR
Let’s be honest: at go-openapi and go-swagger we’ve never been super-strict on code style and linting.
But perhaps now (2025) is the time to adopt a different stance.
Even though our repos have been early adopters of golangci-lint years ago
(we used some other metalinter before), our decade-old codebase is only realigned to new rules from time to time.
Now go-openapi and go-swagger together make up a really large codebase, which is taxing to maintain and keep afloat.
Code quality and the harmonization of rules have thus become things that we need now.
Meta-linter
Universally formatted go code promotes ease of writing, reading, and maintenance.
You should run golangci-lint run before committing your changes.
Many editors have plugins that do that automatically.
We use the golangci-lint meta-linter. The configuration lies in .golangci.yml at the root of each repository.
You may read the linter’s configuration reference for additional reference.
This configuration is essentially the same across all go-openapi projects.
Some projects may require slightly different settings.
Linting rules posture
Thanks to go’s original design, we developers don’t have to waste much time arguing about code figures of style.
However, the number of available linters has been growing to the point that we need to pick a choice.
Our approach: evaluate, don’t consume blindly
As early adopters of golangci-lint (and its predecessors), we’ve watched linting orthodoxy
shift back and forth over the years. Patterns that were idiomatic one year get flagged the next;
rules that seemed reasonable in isolation produce noise at scale. Conversations with maintainers
of other large Go projects confirmed what our own experience taught us:
the default linter set is a starting point, not a prescription.
Our stance is deliberate:
Start from default: all, then consciously disable what doesn’t earn its keep.
This forces us to evaluate every linter and articulate why we reject it – the disabled list
is a design rationale, not technical debt.
Tune thresholds rather than disable when a linter’s principle is sound but its defaults
are too aggressive for a mature codebase.
Require justification for every //nolint directive. Each one must carry an inline comment
explaining why it’s there.
Prefer disabling a linter over scattering //nolint across the codebase. If a linter
produces systematic false positives on patterns we use intentionally, the linter goes –
not our code.
Keep the configuration consistent across all go-openapi repositories. Per-repo
divergence is a maintenance tax we don’t want to pay.
The result is a three-layer defense: the .golangci.yml config as a baseline, //nolint with
mandatory justification for the rare exceptions, and an audit trail for documentation.
Contributors should read the disabled list as a set of conscious choices, not gaps to fill.
We enable all linters published by golangci-lint by default, then disable a few ones.
Here are the reasons why they are disabled (update: Feb. 2026, golangci-lint v2.8.0).
disable:
- depguard # we don't want to configure rules to constrain imports. That's the reviewer's job - exhaustruct # we don't want to configure regexp's to check type name. That's the reviewer's job - funlen # we accept cognitive complexity as a meaningful metric, but function length is not relevant - godox # we don't see any value in forbidding TODO's etc in code - nlreturn # we usually apply this "blank line" rule to make code less compact. We just don't want to enforce it - nonamedreturns # we don't see any valid reason why we couldn't use named returns - noinlineerr # there is no value added forbidding inlined err - paralleltest # we like parallel tests. We just don't want them to be enforced everywhere - recvcheck # we like the idea of having pointer and non-pointer receivers - testpackage # we like test packages. We just don't want them to be enforced everywhere - thelper # too many false positives on test case factories returning func(*testing.T). See note below - tparallel # see paralleltest - varnamelen # sometimes, we like short variables. The linter doesn't catch cases when a short name is good - whitespace # no added value - wrapcheck # although there is some sense with this linter's general idea, it produces too much noise - wsl # no added value. Noise - wsl_v5 # no added value. Noise
As you may see, we agree with the objective of most linters, at least the principle they are supposed to enforce.
But all linters do not support fine-grained tuning to tolerate some cases and not some others.
Note on thelper: the only value we needed from this linter was checking for t.Helper() calls
inside genuine test helpers. Unfortunately, it produces persistent false positives on test case factories
(functions returning func(*testing.T)), which is a pattern we use extensively.
It also enforces naming conventions we don’t subscribe to. The issue has been
reported upstream. We prefer disabling it entirely over maintaining //nolint:thelper directives
across every test file.
When this is possible, we enable linters with relaxed constraints.
settings:
dupl:
threshold: 200# in a older code base such as ours, we have to be tolerant with a little redundancy# Hopefully, we'll be able to gradually get rid of those.goconst:
min-len: 2min-occurrences: 3cyclop:
max-complexity: 20# the default is too low for most of our functions. 20 is a nicer trade-offgocyclo:
min-complexity: 20exhaustive: # when using default in switch, this should be good enoughdefault-signifies-exhaustive: truedefault-case-required: truelll:
line-length: 180# we just want to avoid extremely long lines.# It is no big deal if a line or two don't fit on your terminal.
Code Of Conduct
Our Pledge
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, gender identity and expression, level of experience,
nationality, personal appearance, race, religion, or sexual identity and
orientation.
Our Standards
Examples of behavior that contributes to creating a positive environment
include:
Using welcoming and inclusive language
Being respectful of differing viewpoints and experiences
Gracefully accepting constructive criticism
Focusing on what is best for the community
Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
The use of sexualized language or imagery and unwelcome sexual attention or
advances
Trolling, insulting/derogatory comments, and personal or political attacks
Public or private harassment
Publishing others’ private information, such as a physical or electronic
address, without explicit permission
Other conduct which could reasonably be considered inappropriate in a
professional setting
Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.
Scope
This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.
Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at ivan+abuse@flanders.co.nz. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project’s leadership.
Fuzz tests are handled separately by CI and may reuse a cached version of the fuzzing corpus.
At this moment, cache may not be shared between feature branches or feature branch and master.
The minimized corpus produced on failure is uploaded as an artifact and should be added manually
to testdata/fuzz/....
Coverage threshold status is informative and not blocking.
This is because the thresholds are difficult to tune and codecov oftentimes reports false negatives
or may fail to upload coverage.
Some repositories may have additional integration tests beyond the standard unit
test suite (e.g. go-openapi/strfmt, go-openapi/analysis).
All tests across go-openapi use our fork of stretchr/testify: github.com/go-openapi/testify.
This allows for minimal test dependencies.
NOTES
codecov inherits roles from github. There is no need to create a dedicated account.
However, there is only 1 maintainer allowed to be the admin of the organization on codecov
with their free plan.
The codecov app is installed at the organization level (github.com/go-openapi).
There is no special token to setup in github for CI usage.
A organization-level token used to upload coverage and test reports is managed at codecov:
no setup is required on github.
Automated updates
dependabot
configuration: .github/dependabot.yaml in each repository
Principle:
dependabot applies updates and security patches to the github-actions and golang ecosystems.
all updates from “trusted” dependencies (github actions, golang.org packages, go-openapi packages)
are auto-merged if they successfully pass CI.
go version updates
Principle:
we support the 2 latest minor versions of the go compiler (stable, oldstable)
go.mod should be updated (manually) whenever there is a new go minor release
(e.g. every 6 months).
This means that our projects always have a 6 months lag to enforce new features from the go compiler.
However, new features of go may be used with a “go:build” tag: this allows users of the newer
version to benefit the new feature while users still running with oldstable use another version
that still builds.
contributors
a CONTRIBUTORS.md file is updated weekly, with all-time contributors to the repository
the github-actions[bot] posts a pull request to do that automatically
at this moment, this pull request is not auto-approved/auto-merged (bot cannot approve its own PRs)
Vulnerability scanners
There are 3 complementary scanners - obviously, there is some overlap, but each has a different focus.
configuration: the .cliff.toml is defined as a shared configuration on
remote repo ci-workflows/.cliff.toml
Commits from maintainers are preferably PGP-signed.
Tags are preferably PGP-signed.
We want our releases to show as “verified” on github.
The tag message introduces the release notes (e.g. a summary of this release).
The release notes generator does not assume that commits are necessarily “conventional commits”.
Mono-repos with multiple modules
The release process is slightly different because we need to update cross-module dependencies
before pushing a tag.
A bump release workflow (mono-repo) can be triggered from the github actions UI to cut a release with a few clicks.
It works with the same input as the one for single module repos, and first creates a PR (auto-merged)
that updates the different go.mod files before pushing the desired git tag.
Commits and tags pushed by the workflow bot are PGP-signed (“go-openapi[bot]”).
NOTICE on supplementary license terms (when applicable: original authors, copied code etc)
MAINTAINERS.md: this document, plus possible repo-specific instructions
Reference documentation (released):
pkg.go.dev hosts the Go reference documentation for each package
(see the individual package URLs in the project table)
AI coding agent support
Recent improvements across go-openapi repositories add documentation to support
AI coding agents and improve their productivity. The goal is to guide agents so
that code and contributions stay aligned with our standards.
Each repository may include the following instruction files:
AGENTS.md – top-level agent instructions (often a symlink to .github/copilot-instructions.md)
.github/copilot-instructions.md – instructions for GitHub Copilot
.claude/CLAUDE.md – instructions for Claude Code, with detailed rules under .claude/rules/
These files typically cover:
Go code conventions and formatting (license headers, supported Go versions, etc.)
Linting standards (golangci-lint configuration and //nolint policy)
Reports are centralized in github security reports and visible only to the maintainers.
Reporting a vulnerability
If you become aware of a security vulnerability that affects any go-openapi repository,
please report it privately to the maintainers
rather than opening a publicly visible GitHub issue.
On Github, navigate to the affected project’s “Security” tab then click on “Report a vulnerability”.
LICENSE
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Dashboard
All our repositories at a glance — status, activity and quality, refreshed daily.
ReST over websocket, so you can serve swagger apis over websocket
May 13 2026
Last updated: 2026-07-10 09:19 UTC
Legend
Release — latest GitHub release. Some repos (e.g. doc-site) are not released and show N/A.
CI / CodeQL — latest workflow status on the default branch.
Last updated — date of the most recent commit on the default branch.
Commits since release — commits on the default branch since the latest release (a ❗ marks more than 20).
Open issues — actionable backlog; Open issues (v2 / future) — issues tagged v2 or future/maybe.
Commits MTD / YTD — commits this month / this year; the excl. bots columns omit bot authors.
Total contributors — per repo, all-time contributor count; on the Subtotal/Total rows, the number of
distinct contributors across the scope (not a sum — people contribute to several repos). For forks
(e.g. testify), Total commits and Total contributors count only our own work since the fork
point, not the upstream lineage.
Lint status — conclusion of the lint job in the latest CI run (self-rendered badge).
Cut a release — link to the repo’s bump-release workflow (N/A where not applicable).
Test Coverage / CodeFactor / GoReportCard — badges rendered by external services.
Security alerts — combined count of open security alerts (code scanning + Dependabot + secret
scanning). A ⚠️ precedes the count whenever there are open alerts (e.g. ⚠️ 6), linking to the repo’s
Security overview; it also appears on its own when an alert source could not be read (tool failure or
missing access) — check it manually (hover for detail). 0 means all sources reported clean.
Security reports — ⚠️ if the repo has open (draft / under-triage) security advisories, linking to its
advisories page; blank (—) when there are none.
Blog
Regular summarized updates from the go-openapi maintainers.
go-openapi & go-swagger activity in May 2026 — runtime client diagnostics, go-swagger v0.34.0, and the swag API migration.
Subsections of Monthly News
June 2026
go-openapi and go-swagger had an active June, with 602 commits across 17 repositories. The
month leaned heavily on security hardening — sandboxed file loading, secure spec loaders,
and generator/CI defenses — while two structural moves reshaped the libraries: the
swag / jsonpointer dependency reshuffle and the extraction of go-swagger’s code scanner
into a new go-openapi/codescan repository.
Themes
Security hardening, across the board.swag now sandboxes local file loading behind a
WithRoot option (GHSA-v2xp-g8xf-22pf) and documents the loader’s security implications;
loads added secure loaders and containment options; go-swagger hardened generated
code against untrusted-spec injection and sanitized its examples/artifact CI workflows;
ci-workflows and testify received coverage- and secret-handling hardening.
The swag / jsonpointer reshuffle.jsonpointer was refactored into specialized
sub-package modules, dropped mailru/easyjson as a default dependency, removed most remaining
external dependencies, and gained a new jsonname provider that better respects Go naming
conventions; swag deprecated its own jsonname module (moved to jsonpointer) and added a
generic sync.Pool factory. Shipped as jsonpointer v0.24.0 and swag v0.27.0.
A new repository: go-openapi/codescan. The spec code-scanner previously living inside
go-swagger is now a standalone repo, complete with a Hugo documentation site scaffold, a
grammar preprocessor, and a deterministic golden-test harness; go-swagger was updated to
consume codescan v0.35.0 for swagger generate spec.
testify assertions for go1.26. New ErrorAsType / NotErrorAsType assertions with
go-version-guarded codegen, plus guards against nil interfaces and cyclic inputs in the
reflection walkers, and new fuzz tests. Released as v2.6.0.
go-swagger codegen fixes. Explicit casing for x-go-name is now preserved (#3319, #3357),
an initialisms regression from v0.34.0 was fixed, and an opt-in --with-stringer generates
model String() methods.
Docs alignment and CI cadence. Documentation was aligned with the org template across many
libraries, a shared webhook-announcements workflow (Discord) was added, and the all-time
contributors workflow moved from a weekly to a monthly schedule.
Repository highlights
Repository
Latest release
Highlights
swag
v0.27.0
Sandboxed local loading via WithRoot (GHSA-v2xp-g8xf-22pf); generic sync.Pool factory; jsonname module deprecated
jsonpointer
v0.24.0
Split into specialized sub-package modules; default mailru/easyjson dependency dropped; new jsonname provider
go-swagger
v0.35.0
Generator hardened against untrusted-spec injection; x-go-name casing preserved; opt-in --with-stringer; wired to codescan v0.35.0
codescan
v0.35.0
New repository — code scanner extracted from go-swagger; Hugo docs site; grammar preprocessor
go-openapi and go-swagger had a busy May, with 258 commits across 18 repositories. The
month’s centre of gravity was runtime, which gained connection-level client diagnostics
and a documentation overhaul over the course of six releases, while go-swagger shipped
v0.34.0 on the back of a migration to the new go-openapi/swag API.
Themes
Client diagnostics in runtime. A new Runtime.Trace exposes connection-level
diagnostics, including a TLS diagnostic mode, alongside a build-tagged SkipAuth feature
and a fix for honoring context cancellation in the multipart upload goroutine.
The swag API migration. Both go-swagger and codegen migrated their generators
onto the new go-openapi/swag API; go-swagger’s generated clients became more idiomatic
(context-aware SubmitContext, internal Params fields moved to their own struct).
A wave of releases. runtime cut six releases (v0.29.5 → v0.32.2), go-swagger
reached v0.34.0, and analysis, jsonreference, strfmt and validate all tagged patch
releases; ci-workflows iterated through v0.3.x.
Documentation. runtime received a large docs pass — a media-types selection guide, a
keep-alive primer, a constant-time-comparison contract for auth callbacks, and per-module
READMEs — and analysis clarified its mixin precedence rules.
CI maintenance, org-wide. A shared bot-PR monitoring workflow was rolled out across
most repositories (runtime, analysis, validate, spec, swag, strfmt, …), with follow-up
fixes to bot identity, filters and permissions.
Period: April 1, 2026 — May 29, 2026
Overall effort: 352 commits across 18 repositories (16 go-openapi libraries + the go-swagger toolkit and its examples)
This period was concentrated, feature-driven work rather than the broad organization-wide infrastructure sweeps of the two previous quarters. It had two clear centers of gravity — runtime and codescan — supported by continued factoring of code out of go-swagger, steady maintenance of the test framework and CI platform, and consolidation of organization-wide documentation. Downstream, the go-swagger toolkit broke a long release standstill and shipped v0.34.0; it is covered in §3.
The largest single effort this quarter, runtime progressed from v0.29.3 through v0.32.2 (seven releases). This was a careful refactoring and reorganization of the package layout, not a rewrite: the public v0.29 API surface was deliberately preserved, so the changes are non-breaking for downstream consumers.
A new standalone middleware module. The server middleware was extracted into its own module, github.com/go-openapi/runtime/server-middleware, with no go-openapi runtime dependencies (its only requirement is the test framework). It bundles the documentation UI (docui), typed media-type handling (mediatype), and content negotiation (negotiate) as middleware that is reusable on its own — in any net/http server, including outside the go-openapi ecosystem.
Context-first client request building.
New SubmitContext entry point; BuildHTTP now threads a context.Context end-to-end
request moved to its own internal package; context cancellation honored in the multipart upload goroutine; streaming bodies closed on buildHTTP error paths
OpenTelemetry transport (client-middleware/opentracing) pivoted to SubmitContext; ContextualTransport promoted to the runtime package
Content negotiation and media types.
New typed media-type package with symmetric Accept negotiation; negotiate extracted into the server-middleware module
findByCanonical extracted from Lookup; content-type matching now respects MIME parameters; validateContentType distinguishes 400 from 415
A curl-style connection diagnostic. A new Runtime.Trace adds a curl-style, connection-level diagnostic to the client — surfacing TLS handshake details (with correct PEM labels and Ed25519 key support) to make connection troubleshooting straightforward.
Other additions. A BindForm helper for multipart / urlencoded body binding, and a build-tag-gated SetSkipAuth dev-mode auth bypass with a dedicated unsafe-skipauth tagged CI build.
Security hardening
A focused security pass accompanied the refactor:
Filename length capped on untyped formData uploads; CR/LF stripped from multipart filename and field names
Fuzz targets added for the BindForm parser, filename capping, and the header-parsing surface
Content negotiation rejects q-values greater than 1; CA cert pool cloned rather than shared by pointer; constant-time-comparison contract for auth callbacks documented
Issue cleanup and documentation. This work closed essentially every open issue on the repository — only one remains (#53, a long-standing request that hits an architectural wall and is deferred to a future v2). runtime now also publishes its own documentation site at https://go-openapi.github.io/runtime/, with extensive, detailed code examples.
2. codescan & the diff Package: Factoring Code Out of go-swagger
A long-running goal of the organization is to factor reusable components out of the monolithic, hard-to-maintain go-swagger project into independently versioned go-openapi modules. Two such moves landed this quarter; both began at the Q1 report’s March 17 cutoff, so neither appeared there.
codescan
codescan — the engine that generates an OpenAPI (Swagger) specification by scanning Go source and parsing swagger annotations — was historically the least maintainable and least stable part of go-swagger. It was spun off into its own repository, imported with full history (commits back to 2015), and has since become a major focus.
Merged this quarter:
A new package layout to reason more clearly about code scanning versus annotation parsing (#15), followed by dead-code removal (#17)
A batch of scanner/parser/schema correctness fixes: swagger:type array fallthrough to the underlying type, allOf resolution when a member is a TextMarshaler, aliased TextMarshaler capture, multiple enum values assigned in one statement, stripping the in: parameter/header location and duplicate words from generated descriptions, ignoring annotations buried in prose, and preventing structs marked as strfmt from resurfacing
Configuration via options instead of environment variables (#5), relinting, and a Go toolchain bump
In progress (only partially merged for Q2 — the team is treading cautiously here): a substantial rewrite that retires the 60–70 complex regular expressions at the heart of the tool, replacing them with a structured grammar-based parser (with dedicated sub-parsers and a pluggable diagnostic sink). Parallel efforts aim to improve diagnostics and performance — codescan is memory-bound on large code bases. Only a fraction of this work could be safely merged this quarter; the larger part is still being staged. codescan cut its first go-openapi GitHub release, v0.34.0.
analysis: the diff package
The swagger spec diff functionality — comparing two specifications and reporting compatible versus breaking changes — was imported from go-swagger into the analysis repository as a new diff package, again with full history, and shipped in analysis v0.25.0.
The go-swagger toolkit — the downstream code generator that consumes the go-openapi libraries — is its own articulated effort alongside the libraries, and its Q2 progress is part of the same story. After a long release standstill (no feature release since v0.33.1 in October 2025), go-swagger rebased onto the modernized go-openapi libraries (notably adapted to runtime v0.32.x) and resumed shipping: 29 issues were closed this quarter and v0.34.0 was released on May 29, 2026 (35 commits this quarter, 67 year-to-date).
Release infrastructure modernized. Releases are now produced with goreleaser (ci: release workflow with goreleaser), with automated release notes and Discord announcements — a substantial rework of the release pipeline that took several iterations to stabilize.
Completing the monolith split. Continuing the factoring effort described above, the bundled code examples were spun off into their own repository, go-swagger/examples — imported with full history (340 commits back to 2014) across 22 example projects with generated clients/servers plus custom code. A CI workflow now regenerates the examples and opens an automatic PR against that repository (25 commits this quarter), keeping them in sync with the generator. Together with codescan and analysis/diff, this leaves the core go-swagger repository markedly slimmer.
Code generation modernized. The generator was updated to match the refactored runtime: generated clients now use the idiomatic SubmitContext and expose a context-aware operation interface, internal Params fields (timeout, context) were moved into their own struct, and client-side custom producers/consumers can be configured. The generator’s template repository, funcmaps, and language config were split apart for maintainability, alongside validation-template fixes (aliased primitive $ref required checks, the ReadOnly template, enum operator characters) and codescan annotation-scanner fixes (gRPC/protoc false matches, nil-check panics).
jsonpointer (v0.23.1) reached feature completeness: with support for the RFC 6901 "-" array suffix and a pluggable, non-default JSON name provider now in place, the package fully covers the specification. The JSON name provider lets jsonpointer reconstruct JSON field names from Go structs via reflection. swag (v0.26.0) added a complementary name provider that better respects Go’s conventions for JSON naming.
5. strfmt: Duration Performance
strfmt (v0.26.2) gained a faster and stricter ParseDuration, alongside docs alignment with the org-wide documentation and continued MongoDB integration tests under internal/testintegration.
6. Documentation & Doc Sites
runtime carried out a large documentation effort and now publishes its own doc site at https://go-openapi.github.io/runtime/, with extensive, detailed code examples (see §1)
doc-site (this repository) hosts documentation common to the whole organization — code style, contributing guidelines, and generic maintainer documentation — so individual repos no longer repeat it. It now also publishes news and announcements (cross-posted to the project’s Discord), including these quarterly reports
Across several repositories, per-repo docs were trimmed to point at the organization-wide site, and godoc coverage was completed (notably errors and jsonpointer)
7. testify/v2: Steady Cadence
testify/v2 did not change direction this quarter; it kept pace at roughly one minor release a month (v2.5.0, v2.5.1), following its published roadmap. New assertions continued to arrive incrementally (generic slice/map equality, channel Blocked/NotBlocked, opt-in synctest support in async assertions, JSON/YAML redactors, macOS file-descriptor leak detection), and the migration tool was kept in step. A GitHub discussion is ongoing about whether to restore test-suite support, which was deliberately dropped when the fork was first created.
8. CI/CD & Dependency Management
The shared CI platform — ci-workflows (v0.2.17) and gh-actions (v1.4.14) — is checked for updates daily. A key refinement this quarter: CI-related dependency updates are now throttled before propagating to downstream repositories, so frequently-updated actions (such as taiki-e/install-action) no longer flood every go-openapi repo with churn. ci-workflows also gained a workflow to monitor stalled bot PRs and a fuzz fix for running multiple fuzz tests per package. Dependency maintenance otherwise proceeded across all repositories (testify/v2 bumps, go-openapi dependency cascades, and golang.org/x security updates).
Impact Assessment
Area
Assessment
Big movers
runtime and codescan were the two major efforts. runtime delivered a non-breaking refactor plus a new reusable middleware module; codescan’s work is arguably larger and deeper still, but only a fraction could be safely merged this quarter.
Reusability
runtime’s server middleware is now a standalone module usable in any net/http server, independent of go-openapi.
Security
HTTP request handling was hardened in the runtime layer used by all generated clients and servers.
Maintainability
Factoring codescan, the diff package, and the bundled examples out of go-swagger continues to shrink the monolith and isolate historically hard-to-maintain code.
Downstream (go-swagger)
The generator resumed releases (v0.34.0) after a long standstill once rebased onto the modernized libraries, modernized its release pipeline (goreleaser), and closed ~29 issues.
Test Framework
testify/v2 held a steady, roadmap-driven cadence.
Risk Level
Low–Medium — runtime preserved its public API and added fuzzing/tests; codescan’s riskier rewrite is being staged cautiously, with only the stable pieces merged.
Repository Highlights
Repo
Tag
Status
analysis
v0.25.1
Imported go-swagger’s diff package with full history (v0.25.0); mixin precedence docs
ci-workflows
v0.2.17
Throttles CI updates to downstream repos; stalled-bot-PR monitor; fuzz fix
codescan
v0.34.0
Spun off from go-swagger; package-layout refactor, scanner/parser fixes; regex-removal rewrite in progress
doc-site
—
New repo: organization-wide docs (style, contributing, maintainers) + news/announcements
Feature-complete: RFC 6901 "-" suffix, reflection-based JSON name provider
jsonreference
v0.21.5
Docs point to org-level documentation; dependency updates
loads
v0.23.3
Dependency cascades from analysis/spec
runtime
v0.32.2
Client context refactor, new standalone server-middleware module, curl-style Trace diagnostic, all issues closed but one
spec
v0.22.4
Dependency updates
strfmt
v0.26.2
Faster, stricter ParseDuration
swag
v0.26.0
Go-convention-respecting JSON name provider
testify
v2.5.1
Steady monthly minor releases, roadmap-driven
validate
v0.25.2
Dependency updates
Summary
Q2 2026 was concentrated, feature-driven work rather than the broad infrastructure sweeps of the two previous quarters, with two clear centers of gravity: runtime and codescan.
runtime was refactored and reorganized rather than rewritten: a context-first client, a new standalone server-middleware module reusable in any net/http server, a curl-style connection diagnostic, and a focused security pass — all while preserving the v0.29 public API. The effort closed essentially every open issue on the repository (one long-standing item remains, deferred to a future v2) and shipped alongside a new runtime documentation site.
codescan, freshly spun off from go-swagger, was refactored around a clearer package layout and is undergoing a cautious, still-in-progress rewrite to retire the 60–70 regular expressions that drove its annotation parsing, with parallel work on diagnostics and performance. Only a fraction of that effort could be merged this quarter; the larger part is still being staged. The diff package was likewise imported from go-swagger into analysis. The feature libraries advanced too: jsonpointer reached feature completeness, swag refined Go-aware JSON naming, and strfmt tightened duration parsing.
Downstream, the go-swagger toolkit returned to active releases after a long standstill: once rebased onto the modernized go-openapi libraries it closed some 29 issues, moved its release process to goreleaser, completed the monolith split by spinning off its bundled examples into a dedicated repository, and shipped v0.34.0.
The organization’s infrastructure stayed healthy in the background: testify/v2 kept a steady, roadmap-driven cadence; ci-workflows and gh-actions continued to centralize CI and now throttle updates to downstream repos; and the new doc-site consolidated organization-wide documentation and announcements. No breaking API changes were introduced.
Most go-openapi repositories have now reached a satisfactory level of maturity — in code quality, documentation, and a low count of pending issues. The expectation is that most of them (codescan being the likely exception — it needs another push) will be released as v1.0 at some point next quarter, clearing the way to begin work on a v2.
Thanks to Our Contributors
A warm thank-you to the community members who contributed to go-openapi and go-swagger this quarter. Whatever its size, every contribution helps keep the project healthy — we’re grateful for your time and care:
Period: December 7, 2025 — March 17, 2026
Overall effort: 674 commits across 14 repositories
1. Migration to go-openapi/testify/v2 (Organization-Wide)
Building on the testify/v2 fork introduced in the previous period, this quarter completed the organization-wide migration. All 14 repositories now use go-openapi/testify/v2 as their test framework.
Automated migration: A dedicated v1→v2 migration tool was built and used to transition existing test suites, handling import rewrites and API changes systematically.
Generics adoption: testify/v2 introduced first-class support for Go generics, with 17+ new generic assertions (IsOfType[T], SeqContains/SeqNotContains, JSONMarshalAsT, YAMLMarshalAsT, and more). Several repositories — notably swag and analysis — upgraded their test suites to leverage generics.
New safety assertions:NoGoRoutineLeak and NoFileDescriptorLeak (Linux) detect resource leaks in tests.
.claude/rules/github-workflows-conventions.md — generalized from ci-workflows to all repos
3. CI/CD Maturation and Mono-Repo Release Automation
Continuing from the previous period, the shared workflow platform matured and stabilized. The major new capability is mono-repo release automation — enabling strfmt, testify, swag, and analysis to tag and release sub-modules correctly.
ci-workflows: mono-repo variants for test/release/coverage, fuzz testing with corpus caching, remote shared git-cliff config, Trivy upgrade, cross-org workflow reuse.
gh-actions: four new composite actions (detect-go-monorepo, next-tag, bot-credentials, wait-pending-jobs). High commit counts (145/59) reflect iterative testing difficulty, not change scope.
This period continues and consolidates the infrastructure work reported in December 2025. The three main threads are: test framework migration, CI/CD stabilization, and dependency footprint reduction.
The organization-wide migration to go-openapi/testify/v2 is now complete. All 14 repositories use the fork, and several have adopted its generics-based assertions. The automated migration tool and the addition of safety assertions (goroutine and file descriptor leak detection) make testify/v2 a meaningful upgrade over the original stretchr/testify, not just a fork.
The CI/CD platform, which underwent its initial overhaul in the previous period, matured into a stable mono-repo-aware system. The major new capability — automated mono-repo releases with correct sub-module tagging — required iterative hardening but is now operational across strfmt, testify, swag, and analysis.
The strfmt BSON decoupling removed the MongoDB driver from the transitive dependency graph of every downstream go-openapi consumer, a structural improvement with no breaking changes.
AI agent instructions were deployed across all repositories, establishing a consistent onboarding experience for both human and AI-assisted contributors. No breaking API changes were introduced during this period.
Enhanced NOTICE files with comprehensive copyright information
Added Apache 2.0 license headers to source files
Minor documentation corrections (typos in NOTICE files)
Impact Assessment
Organizational Consistency: Systematic improvements to infrastructure, governance, and code quality have been applied across the go-openapi ecosystem.
Automation & Efficiency: Shared workflows and reusable actions reduce maintenance burden. CI/CD infrastructure updates can now be made centrally in ci-workflows rather than individually in each repository.
Contributor Experience: Documentation improvements (CONTRIBUTING, DCO, MAINTAINERS, STYLE guides) and automated contributor recognition provide clearer guidelines for contributors.
Code Quality: Linting configuration standardization and testing improvements (including fuzz testing) have been applied systematically.
Release Management: Automated release workflows (bump, tag, release) standardize version management and reduce manual work.
Risk Level: Low — most changes are infrastructure and documentation improvements that don’t affect core library functionality. Code changes (linting fixes, test migrations) are low-risk refactorings.
Repository-Specific Highlights
ci-workflows (v0.1.1)
Status: New central infrastructure repository (v0.1.0 released)
Hosts all shared GitHub Actions workflows
Provides configuration templates for other repositories
Includes documentation templates
Focused on establishing and refining shared infrastructure
gh-actions (v1.1.0)
Status: New repository providing reusable composite actions
Developed organization-wide tooling (svu for versioning, test reporters)
Created reusable actions for common tasks
Iterative development with extensive CI/CD refinement
jsonpointer (v0.22.3)
Status: Major testing and documentation improvements
Previously lagging behind, now fully aligned with other repositories
Adopted all standard CI/CD workflows and documentation
errors (v0.22.4)
Status: Minimal but consistent updates
Dependency updates
Test migration to internal testify
Experimental markdown linting
Summary
The go-openapi organization underwent a coordinated modernization effort over the past month, centered on three pillars:
Infrastructure: Creation of shared CI/CD workflows (ci-workflows) and reusable actions (gh-actions) that reduce duplication across 8 repositories. Updates to CI/CD infrastructure can now be made once and consumed by all repositories.
Governance: Establishment of documentation standards (CONTRIBUTING, DCO, SECURITY, MAINTAINERS, STYLE) that formalize project governance and contributor onboarding processes.
Quality: Systematic linting improvements, testing enhancements (including fuzz testing in jsonpointer), dependency updates, and security scanning across the organization.
No breaking changes or major feature work occurred during this period. The focus was entirely on operational improvements and establishing infrastructure for long-term maintenance. The coordinated nature of these changes — touching 7 of 8 repositories with similar patterns — indicates a planned, organization-wide effort rather than ad-hoc improvements.
