graphql / graphql/graphql-spec
Consider speciesist language in specification documentation
- Dominant language
- JavaScript
- Stars
- 14.6k
- Forks
- 1.2k
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
This issue raises awareness of speciesist language patterns in the GraphQL specification and proposes that future writing consider more inclusive alternatives. This is not a request to rewrite existing examples wholesale, but rather a suggestion that the specification's style guide and editorial process consider this dimension going forward.
## What is speciesist language?
Speciesist language uses animals in ways that reinforce their status as property, objects, or lesser beings. In technical documentation, this often manifests as examples that model animals as owned objects with commands to obey — framing that normalizes dominion over other sentient beings. While seemingly innocuous, the cumulative effect of these patterns across technical specifications, tutorials, and documentation shapes how we think about our relationship with other species.
## Findings in the current specification
### The Pet/Dog/Cat example schema (Section 5 — Validation)
The entire validation section (the largest section of the spec) uses a `Pet`/`Dog`/`Cat` example schema as its primary illustration. This schema contains approximately **100+ references** to these animal types across hundreds of code examples. Key patterns include:
- **`owner: Human`** — Animals modeled explicitly as property of humans (8 occurrences)
- **`doesKnowCommand(dogCommand: DogCommand!)`** — Animals modeled as beings that exist to obey commands
- **`isHouseTrained(atOtherHomes: Boolean)`** — Animals modeled through the lens of their obedience/utility to humans (17 occurrences of `isHouseTrained`)
- **`DogCommand` enum with values `SIT`, `DOWN`, `HEEL`** — Reinforcing the command-obedience framing
- **`barkVolume: Int` / `meowVolume: Int`** — Reducing animal communication to a measurable nuisance
- **`interface Pet` / `union CatOrDog`** — The term "pet" itself frames animals as existing for human companionship rather than as beings with their own interests
The schema models a world where animals are property (`owner`), exist to follow commands (`doesKnowCommand`), are valued for their obedience (`isHouseTrained`), and are categorized by their utility to humans (`Pet`).
### Other instances
- **`pets: [Pet]`** in Section 3 (Type System) as the canonical example of List types
- **"chicken-or-egg dilemma"** in CONTRIBUTING.md (line 29) — an animal-derived idiom
### What the spec does well
The specification does not use many of the commonly flagged terms in inclusive language guides (no master/slave, no blacklist/whitelist, etc.). The style guide already emphasizes neutral, descriptive tone. This suggests the project is receptive to thoughtful language considerations.
## Proposal
This is **not** a request to immediately refactor the entire validation section. That would be a massive editorial undertaking given the 100+ references deeply woven through the examples. Instead, this issue proposes:
1. **Awareness for new writing**: When new examples, sections, or significant editorial changes are written, consider using example schemas that don't model animals as property. Alternatives could include books/authors, products/categories, vehicles/manufacturers, projects/contributors, or any other domain that doesn't reinforce hierarchies over sentient beings.
2. **Style guide consideration**: The existing [STYLE_GUIDE.md](https://github.com/graphql/graphql-spec/blob/main/STYLE_GUIDE.md) covers tone, formatting, and conventions well. A brief note about considering inclusive example domains (not just inclusive pronouns/terms, but inclusive *framing*) when writing new content could be valuable.
3. **Gradual evolution**: If major editorial work is ever undertaken on the validation section examples, consider this dimension as part of that work.
## Context
The tech industry has increasingly recognized that language in specifications and documentation matters — efforts around master/slave terminology, gendered language, and other inclusive language initiatives have been widely adopted. Speciesist language is a natural extension of this same principle: that our default examples and metaphors shape assumptions about who and what matters.
Other specifications and style guides that have considered inclusive language:
- [IETF Terminology, Power, and Inclusive Language (RFC draft)](https://datatracker.ietf.org/doc/draft-knodel-terminology/)
- [Chromium Inclusive Code](https://chromium.googlesource.com/chromium/src/+/master/styleguide/inclusive_code.md)
- [Linux kernel inclusive terminology](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=49decddd39e5f6132ccd7d9fdc3d7c470b0061bb)
These precedents focused on racial and gendered language, but the underlying principle — that normative technical documents should not casually reinforce hierarchies over any group of sentient beings — applies equally here.
## What this is not
- This is not a request for immediate, sweeping changes
- This is not a criticism of the spec authors' intentions
- This is not asking GraphQL to take a political position on animal rights
It is simply a request to consider, as a matter of editorial awareness going forward, whether examples that model animals as obedient property are the best choice when neutral alternatives exist.
Contributor guide
Assessment
This issue has not been assessed yet.