Naming and structure conventions that keep models readable at scale.
Consistent conventions make a model easy to scan, diff, and extend. These guidelines keep a growing model coherent across contributors.
Naming
| Element | Convention |
|---|---|
| Slugs | Stable, lowercase, snake_case or kebab-case |
| Titles | Human-readable, capitalized |
| Links labels | Short verbs (calls, reads from) |
| Tags | group:value from the shared taxonomy |
Slugs are contracts
Slugs appear in object paths that links and routes depend on. Choose them carefully and avoid renaming once others reference them.
Structure
One concern per file
After the first level, give each object its own file for clean diffs.
Consistent depth
Use nesting to reflect real containment, not to force a uniform shape.
Use the schema
Prefer schema-defined types and fields over ad-hoc attributes.
Descriptions
- Keep object descriptions to one or two sentences.
- Describe responsibility, not implementation trivia.
- Update descriptions when responsibilities change.
Tags and taxonomy
- Reuse existing tag groups.
- Apply tags consistently for filtering.
Agree on conventions as a team and apply them from day one. Retrofitting a style guide onto a large model is far more work than following one.
Last updated on