API Evangelist API Evangelist
API Learnings
APIs
API Governance
API Solutions
API Discovery
API Building Blocks
API Evangelist LLC

OpenAPI Schema Property Names

Keeping up with the latest versions of the specification.

The names of schema properties should be plain language, follow a consistency structure and casing. These properties should all work in concert to deliver a useful digital representation as needed for an API request, and expected as a response. Don’t make property names cryptic, and if possible driven from a central vocabulary to help keep consistent.

Naming is hard, and both product and engineering should be equipped to weigh in on the naming of properties, as well as the policies and rules that govern the naming of schema property names. Names should be consistent across all object properties, with intentional reuse of properties, and modular references of common properties used across many different objects.