Consider speciesist language in specification documentation

[stuckvgn]

Summary

The OpenAPI Specification has made commendable progress adopting inclusive language practices in its technical terminology (e.g., the industry-wide shift from master/slave to primary/replica, and master to main for default branches). This issue proposes extending that same thoughtfulness to consider speciesist language — terminology and examples that normalize the commodification of animals.

The "Petstore" Example

The most prominent instance is the Petstore example, which is deeply embedded throughout the specification and the broader OpenAPI ecosystem:

• The canonical example API in the specification document is a pet store — a business model built on treating animals as commercial products to be bought, sold, and inventoried.
• In the current 3.2.0 specification alone, there are 600+ references to pet/animal-related terms (Pet, Dog, Cat, petstore_auth, write:pets, read:pets, breed, petType, etc.).
• Animals in these examples are modeled as inventory items with properties like breed, petType, and status, reinforcing a framing of animals as commodities rather than sentient beings.
• The Petstore example is the first thing millions of developers encounter when learning OpenAPI, via the specification itself and the Swagger Petstore demo.
• Schema examples use Cat and Dog as discriminator examples with language like "A pet cat," "A pet dog," "the size of the pack the dog is from."

Specific locations in the 3.2.0 specification

Section	Usage
Info Object Example (line 205)	title: Example Pet Store App
Security Scheme Examples	petstore_auth, write:pets, read:pets
Path Item / Paths Examples	/pets/{petId}, /pets/mine, "Returns all pets"
Discriminator Object Examples	Pet, Cat, Dog schemas with breed, petType
XML Object Examples	animals, dog, cat, hamster arrays
OAuth2 Scope Examples	write:pets: modify pets in your account

Precedent

This follows the same pattern as other inclusive language efforts the tech industry has adopted:

• master → main (Git default branch naming)
• master/slave → primary/replica or leader/follower (database terminology)
• whitelist/blacklist → allowlist/blocklist
• sanity check → validation check

The OpenAPI Specification has already adopted main as its default branch. This proposal extends the same principle to language that normalizes the commodification of non-human animals.

Proposal

1. Add speciesist language awareness to the style guide — a brief note encouraging contributors to avoid examples that frame animals as products or commodities, alongside the existing style guidance.

2. Transition the canonical example away from the Petstore model — future specification versions could adopt an example API that doesn't center on animal commodification. Possible alternatives:

   • A bookstore or library API
   • A music/playlist API
   • A task/project management API
   • A recipe/cookbook API

   The style guide already notes: "In examples, use realistic values rather than foo/bar." A non-animal-commodification example can be equally realistic and instructive.

3. Review animal-related idioms — while the current spec avoids common idioms like "guinea pig," "canary deployment," or "beating a dead horse," this awareness should be part of the documented style guidance for future contributions.

Scope and Approach

• This is not a request to change published specification versions (which, per the CONTRIBUTING.md, are never modified).
• This could be addressed incrementally in future patch or minor releases.
• The Petstore example has deep roots across the ecosystem (Swagger UI, code generators, tutorials), so a transition would necessarily be gradual and coordinated.
• A style guide addition could be implemented immediately on the main branch.

Why This Matters

The OpenAPI Specification is used by millions of developers worldwide. The examples and language choices in the specification shape how developers think about API design. When the canonical example treats animals as inventory items to be managed via CRUD operations, it subtly normalizes that framing.

The tech industry has recognized that language choices in specifications and documentation carry weight — that's why the shifts away from master/slave and whitelist/blacklist happened. Speciesist language deserves the same consideration.

This is a small change with meaningful impact: choosing examples that don't require developers to model living beings as products.

[karenetheridge]

ai;dr

[handrews]

@karenetheridge at least the LLM read the CONTRIBUTING.md guide!

@stuckvgn FWIW, the petstore example is purely a historical artifact. I thought we'd actually replaced it on learn.openapis.org but I guess not. As with most things, the way change happens is that someone volunteers to do the work. I, personally, am notoriously bad at writing examples, so I won't be coming up with a replacement. But the petstore example isn't even a really good example of where the OAS is now anyway.