# The AIP corpus is a design document set with a site generator, not an API framework

> google.aip.dev is hundreds of numbered design documents describing how Google designs APIs, built on the Python enhancement proposal model, with a Jekyll-style generator and a Docker image for reading them locally. What an engineering team is actually adopting is a review process, and the repository is candid about where the guidance stops being general.

**aip-dev/google.aip.dev** — API Improvement Proposals. https://aip.dev/

- Repository: https://github.com/aip-dev/google.aip.dev
- Stars: 1,639 · Forks: 823
- Language: Shell
- License: NOASSERTION
- Published: 2026-09-30 · Updated: 2026-09-30 · Language: en
- Canonical page: https://hysenlabs.com/projects/aip-dev-google-aip-dev

## The proposal model, borrowed from Python, is the actual contribution

The readme describes the format before it describes the content. An AIP is a design document giving high-level, concise documentation for API development, and the stated goal is for these documents to serve as the source of truth for API-related documentation inside Google and as the way API teams discuss and come to consensus on guidance. The mechanism named for it is Python's enhancement proposals, which the readme credits with having worked well over the years. That is a deliberate borrow and it explains the whole design: numbered documents, each on one topic, each with a status, each argued in public before it becomes guidance. The value of that shape is not the individual rules but the fact that a design conversation can be pointed at a number. A team arguing about whether an update method should return the resource or nothing has a document to read, and one arguing about field naming has a different document. Compare that with an unwritten house style, which is held in people's heads and re-litigated per review. The readme's own summary, that AIPs are lots of documents on how Google does APIs, understates the process machinery but is accurate about the artefact.

## Number blocks that override general guidance are the escape hatch

One paragraph in the readme carries more design information than the rest of the document combined. It says that while much of the API-related guidance is general across different products, some teams in different areas have different customs, styles or guidance, and that separate blocks of numbers have been provided for those areas where they might override or extend the more general guidance. Number blocks are a sophisticated answer to a real failure mode. A design guideline set that cannot be locally adjusted gets either obeyed in letter and violated in practice, or ignored entirely, and both outcomes destroy its value. Number blocks let a domain keep the general principle and substitute its own exception, with the exception carrying its own number so a reader knows they are reading an override rather than a contradiction. It also makes the corpus extensible by outside adopters in a specific way: an organisation that adopts the general guidance can add its own numbered block without forking the corpus, and the readme points at a separate guide for adopting AIPs in a company, which walks through using them and writing organisation-specific guidance. That guide is the piece to read first if you are considering this, because it addresses the question the corpus itself cannot answer, which is how a general guideline becomes a local standard.

## The site is a pinned generator, and the pin is a maintenance fact

The repository is not a documentation website with source files, it is source files plus a site generator, and the generator is pinned in a way that deserves attention. The requirements file contains a single dependency, installed straight from a git repository at a specific commit hash, with a comment noting it corresponds to version 0.6.6 of the generator. Pinning to a commit rather than a tag means the build is reproducible, and the comment mapping the commit to a release gives a human-readable label. The other half of the pin is a constraint inside the container build, which installs a version of setuptools below a ceiling and turns off build isolation before installing requirements, and adds a compiler toolchain before doing so and removes it afterwards. That is the pattern of installing a source distribution that has not been modernised for current packaging, which is worth knowing before you attempt a local build: it is not that the project is broken, it is that the toolchain is a few years behind and the workaround is encoded in the Dockerfile. The top-level layout confirms the shape: an aip directory holding the proposals, a config directory, a pages directory, a requirements file, a container file, a serve script, a domain configuration file, and prettier configuration for formatting the text. There is no code to speak of. The primary language is recorded as shell because the entry point is a script.

## Reading the site locally means running a container that mounts the checkout

The container file explains itself in a comment that is unusually honest: there is no code in the image, it is pulled from the repository by mounting the directory, with a reference to the serve script.

```dockerfile
FROM python:3.8-alpine
EXPOSE 4000
EXPOSE 35729
ENTRYPOINT ["aip-site-serve", "."]
```
 So the image provides the runtime and the generator, and the proposals come from your checkout at run time. That is a good design for editing, because you rebuild nothing when you change a document, and it means the container is only as stale as the pinned generator commit. The image is based on a slim Alpine Python image, installs the requirements, sets the Flask environment variable to development, exposes two ports, and runs the generator's serve command against the mounted directory. The comment in the file reminds you that publishing a port requires passing the publish flag to the container run command, which is the step people miss when the site appears unreachable on a default port. The two exposed ports are the application and a development reload channel. Nothing in the readme explains the serve script, so the workflow is: build the image, run it with your checkout mounted, publish the port, and open the site. For a read-only audience the published site is the sensible route; the container is for contributors and for organisations mirroring the corpus internally.

## Licensing is split, and the split is deliberate

The licence section does something that many documentation repositories do not, and it matters here. Except as otherwise noted, the content of the repository is licensed under Creative Commons Attribution 4.0, and code samples are licensed under Apache 2.0. Both full texts are in a licence file in the repository, and the readme also links to the developer site policies. The split is the correct arrangement for a document set containing code: the prose is a creative work that benefits from being quotable with attribution, which is what a design guideline corpus needs if teams are going to fork it into internal documentation, while the code samples are meant to be copied and are licensed permissively so that copying them into a codebase does not drag an attribution requirement into your project. The qualification that some content is otherwise noted is the usual escape hatch for third-party material. If you are planning to adopt these documents internally, the practical reading is that you may quote the prose with attribution and lift the samples without obligation, which is exactly what a standards body wants. If you are redistributing a mirrored corpus wholesale, read the otherwise-noted items first, because a small number of documents are likely to carry their own terms.

## How current is it, and how do you find anything in it

The maintenance picture is mixed and should be described precisely. Published releases exist and are date-named rather than version-named: one in December 2024, one in November 2024, one in September 2024. The last push to the master branch was on 2026-08-17, which is well after the newest tag. So the corpus is being edited, and those edits are not producing new tags on a schedule. For a reference document set that is not fatal, since a design guideline does not have a breaking-change surface the way a library does, but it does mean you should record which revision you read if you are going to cite a specific rule in a design review, because the number will not change while the wording might. The other practical question is retrieval. A corpus of this size is only useful if you can find the document you need, and the readme points newcomers at a frequently asked questions page, adopters at the adoption guide, and contributors at a contributing document. The structure implies a numbered, topic-indexed site rather than prose, which is the right shape for a reference, and the number-block mechanism described earlier is also a navigation aid: if your problem is in a specific domain, the block index tells you which numbers to read first.

## Conclusion

Adopt the AIP corpus as a review checklist if you build resource-oriented HTTP APIs and want a second opinion on naming and method semantics, since the value is in the numbered principles that make design disagreements concrete rather than in any code you can install. Do not adopt it as a framework, because there is nothing to import: this is a documentation set with a static site around it, and its authority comes from Google's internal practice rather than from a standard anyone has ratified. Three things to know before you rely on it. That it is explicitly extensible, since the readme says separate number blocks exist for areas that need to override or extend the general guidance, so an AIP that conflicts with a constraint in your industry is a case to handle rather than an error in the guidance. That the newest published releases are dated tags from late 2024 while the last commit was on 2026-08-17, so the site is being edited without new version tags. And that the licence is split, with the prose under Creative Commons Attribution 4.0 and the code samples under Apache 2.0, which matters if you intend to quote the text in your own internal documentation. The site generator itself is pinned to a specific commit, and that pin is worth understanding before you try to run it.

## FAQ

### What are AIPs and what are they used for?

API Improvement Proposals are numbered design documents providing high-level, concise guidance for API development. The stated goal is that they serve as the source of truth for API documentation inside Google and as the way API teams discuss and reach consensus on API guidance, modelled on Python's enhancement proposals.

### Can I use the AIP guidance outside Google?

The readme points to a guide for adopting AIPs in a company, which walks through starting to use the general proposals and writing your own organisation-specific guidance. The readme also notes that separate number blocks exist for areas that need to override or extend the general guidance.

### What licence applies to the AIP content and code samples?

Except as otherwise noted, the content is licensed under Creative Commons Attribution 4.0 and the code samples under Apache 2.0. The full texts are in the licence file in the repository, and the readme also links to the developer site policies.

### How do I read the AIP site locally?

The container file contains no code and instead expects your checkout to be mounted into it, with a serve script handling the run command. The image installs the pinned site generator, sets the Flask environment to development, exposes two ports, and runs the generator's serve command; the file notes you must pass the publish flag to the container run command to reach a port.

### How current is the google.aip.dev repository?

Published releases are date-named tags from 2024, most recently 2024-12-03, while the last push to the master branch was on 2026-08-17. The corpus is therefore still being edited even though the newest tag is from late 2024.

## Sources

- [aip-dev/google.aip.dev on GitHub](https://github.com/aip-dev/google.aip.dev)
- [Issues](https://github.com/aip-dev/google.aip.dev/issues)
- [README](https://github.com/aip-dev/google.aip.dev/blob/master/README.md)
- [Releases](https://github.com/aip-dev/google.aip.dev/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aip-dev-google-aip-dev