At a glance#
Wire names are lower snake_case. The runtime rejects a camelCase property in a request body, so a specification that declares one describes a request that fails. The OpenAPI file of the platform is generated from the same names the runtime reads and writes.
| Where | Style | Example |
|---|---|---|
| JSON property | snake_case | customer_id, created_at |
| Query parameter | snake_case | per_page, sort_by |
| Path segment | lower-case kebab-case | kyc-kyb, platform-subscriptions |
| Path variable | snake_case | {order_id} |
| Enum value | snake_case, or UPPER_SNAKE_CASE when it mirrors a Java enum | shipped, IN_REVIEW |
| Header name | Hyphen-Case, as HTTP writes it | Idempotency-Key, Accept-Language |
| Error code | snake_case | quota_exceeded |
Properties and parameters#
A name is lower case, with digits and single underscores between words. It starts with a letter. orderId, OrderID, order-id and order__id are refused.
{
"order_id": "ord_1042",
"customer_id": "cus_77",
"item_count": 3,
"created_at": "2026-10-17T09:30:00Z"
}Timestamps are ISO 8601 in UTC. An amount carries its currency in a sibling property, for example amount and currency with a value such as SAR.
Enum values#
A new enum uses snake_case values. An enum that mirrors a Java enum keeps the UPPER_SNAKE_CASE of that enum: the platform's own specifications hold several hundred such values. Both are accepted. Kebab-case, camelCase, mixed case and values with spaces are refused.
Paths#
A path segment is a plural noun in lower-case kebab-case. A path variable is the singular name of the identifier in snake_case. A path variable is positional on the wire, so a different style there never breaks a client; the ruleset reports it as a hint for a provider, because generated clients use the name for their arguments.
Checked by#
| Rule | Severity | Checks |
|---|---|---|
api360-property-snake-case | error | Every schema property name |
api360-query-param-snake-case | error | Every query parameter name |
api360-path-param-snake-case | hint | Every path variable name (off for the platform's own specifications) |
api360-enum-value-case | warn | Every string enum value |
api360-path-kebab-case | warn | Every literal path segment |
See also#
- Linting a specification: run the rules on your file.
- Errors: the
snake_caseerror code and body.