PackageList: the JSON list that decides what the Swift Package Index shows

The index is a file, and the file is public

The PackageList repository is described as the canonical list of repositories indexed by the Swift Package Index, and the repository listing shows what a catalogue like that actually consists of.

There is packages.json, which is the list itself. There is denylist.json, which is the opposite of the list. There is custom-package-collections.json, for the groupings the index shows. And there is validate.swift, the checker that runs against submissions, plus a .stats.swift file and a .github/ directory holding the workflows. The README carries a badge for a workflow named Valid JSON, which is the check that the catalogue file stays parseable.

The list is not hidden behind an API and not served from a database. It is a JSON file in a git repository, which means the entire membership of the Swift Package Index is inspectable with a browser and a diff. The last push was on 2026-10-19, and the repository publishes no GitHub releases, so the history of the catalogue is the commit history.

The project is Apache-2.0 licensed and the primary language recorded for it is Swift, which is a consequence of validate.swift being a Swift program rather than of the JSON being generated by a script.

The homepage is swiftpackageindex.com, and the topics are spm and swift. So the shape is clear: a public data file plus a validator, with a website and a set of automations on top of it.

Eight requirements, and no quality threshold

The README is direct about who can be listed. Anyone can add a package to the index, and you can submit any package repository, whether it is written by you or by someone else. There is no quality threshold. As long as the packages are valid and meet the listed requirements, they will be accepted, and if you are unsure about any requirement you can submit the packages and the maintainers will help.

The requirements themselves are mechanical rather than editorial, which is the point. The package repositories must all be publicly accessible. The packages must all contain a valid Package.swift file in the root folder. The packages must be written in Swift 5.0 or later. The packages should have at least one release tagged as a semantic version.

Then come the two checks that matter most, because they are the ones that fail in CI rather than in review. The packages must all output valid JSON when running the package dump command with the latest Swift toolchain, and the packages must all compile without errors. The command in question is:

swift package dump-package

The last two requirements are about the metadata rather than the code. The package URLs must include the protocol, usually https, and the .git extension, and all package content must comply with the code of conduct.

A team that has never built a Swift package should be able to read that list and check itself against it in ten minutes. Nothing there asks whether the package is useful, well documented or maintained. That is a deliberate position, and it has consequences for anyone using the index as a discovery tool rather than as a directory.

Submission and removal are both issues

The submission mechanism is an issue on the repository, and the README makes the point that a package can be added by someone who did not write it.

There is an Add Packages button in the README that links to the issue creation page for the repository, and a second link for requesting removal of a package, described as a GitHub workflow. So both directions, adding and removing, run through the same place, which is the natural shape for a catalogue that is a git file.

For a maintainer of a Swift package, the practical sequence is short. Open the issue, describe the repository, and the maintainers will run the checks and the build against it. The README offers help with the requirements rather than a form to fill in, which tells you the process is conversational, and it also tells you that submissions are accepted for packages you did not write, so a colleague can list your package if you do not want to do it yourself.

The removal route is worth noting too. A package that has become unavailable or that a maintainer wants withdrawn can be requested through the same issue mechanism, and the denylist file in the repository is where that decision is recorded.

The DocC note adds a second, quieter channel. The build system can generate and host DocC documentation and make it available from the package's page in the index, and all that is needed is a little configuration data so the index knows how best to build the documentation. The linked page on common use cases covers the manifest configuration for it, which is the piece a package author needs in order to get rendered API documentation rather than a text README on their index page.

Badges turn a package page into a compatibility report

The second note in the README is about how package authors keep their index page current, and it uses the index as a badge server.

If you are submitting your own packages, you are asked to add shields.io badges to your package's README so that the Swift version and the platform compatibility information are readily available and up to date. The mechanism is that the index exposes badge endpoints, and the example given pulls from the package's page on the index for two badge types, one for platforms and one for Swift versions, using a small package as the illustration.

Once a package appears in the index, there is a link in the right-hand sidebar of the package page reading Do you maintain this package?, and using it gives you the markdown to paste into your own README.

So the index is doing two things at once here. It is the source of the compatibility data, because it builds each package against toolchain and platform combinations and knows the results, and it is the distribution point for that data as a badge, which is what makes it visible to anyone who reads the repository rather than to anyone who visits the index.

That is a good design for an ecosystem where toolchain compatibility is the question people actually ask. The alternative, a paragraph in a README that goes stale within a release cycle, is exactly the problem the badge removes.

What a catalogue with no threshold does and does not tell you

The absence of a quality threshold is the fact to hold on to when reading the index, and it cuts both ways.

For a developer looking for a package, the index guarantees that what is listed is real, buildable and publicly reachable, and that the toolchain and platform data attached to it was measured rather than guessed. It does not guarantee that the package is maintained, that its API is stable or that its maintainer answers issues, because none of that is checked.

For the ecosystem, that is the right trade. The alternative, an editorial process with a review queue, would scale badly for something whose job is to be a complete list, and it would put a gatekeeper between a developer and the exposure of their work. The README's commitment, that anyone can add a package and the maintainers will help with the requirements, is the same idea expressed as a policy: the index is neutral about quality and strict about form.

Two structural limits follow. The list can only contain packages that are publicly accessible, so a private or internal package is out of scope by definition. And the validator is the gate, which means a package that compiles with one Swift toolchain and fails with the next can fall out of the index or behave oddly, and the README's requirement that packages compile without errors and dump valid JSON with the latest toolchain is what keeps that churn visible.

The two JSON files at the root are the practical consequence of all this. packages.json is what is listed, denylist.json is what is deliberately not, and custom-package-collections.json is the editorial layer on top, where the index groups packages for browsing.

Editorial conclusion

Adopt this repository as the reference for what the Swift Package Index contains, and submit your own package through it if you want to be listed, because the flow is an issue rather than an application. Do not treat inclusion as an endorsement, since the index states plainly that there is no quality threshold and that anyone can submit a package written by someone else. Before you submit, check the eight requirements yourself, because they are mechanical: a valid Package.swift at the root, Swift 5.0 or later, at least one semantic version tag, a URL with the protocol and the .git extension, and a package that compiles and dumps valid JSON with the latest toolchain.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. SwiftPackageIndex/PackageList on GitHub