diff --git a/api-guidelines/global/json/naming-conventions/rules/should-use-camel-case-for-property-names.md b/api-guidelines/global/json/naming-conventions/rules/should-use-camel-case-for-property-names.md index 25777bde..ffec4a1c 100644 --- a/api-guidelines/global/json/naming-conventions/rules/should-use-camel-case-for-property-names.md +++ b/api-guidelines/global/json/naming-conventions/rules/should-use-camel-case-for-property-names.md @@ -4,7 +4,7 @@ id: R004010 # SHOULD use camelCase for property names -Property names of JSON objects should be formatted in camelCase. +Property names of JSON objects should be formatted in camelCase, and digits should be avoided. DO @@ -12,7 +12,8 @@ DO { "name": "John", "jobDescription": "product manager", - "vacationDays": 37 + "vacationDays": 37, + "entryDate": "2023-01-15" } ```` @@ -22,6 +23,7 @@ DON'T { "NAME": "John", "job-description": "product manager", - "vacationdays": 37 + "vacationdays": 37, + "1stDay": "2023-01-15" } ```` diff --git a/api-guidelines/rest/resources/naming-conventions/rules/must-use-camelcase-for-query-parameters.md b/api-guidelines/rest/resources/naming-conventions/rules/must-use-camelcase-for-query-parameters.md index 9cf0c974..10efef7f 100644 --- a/api-guidelines/rest/resources/naming-conventions/rules/must-use-camelcase-for-query-parameters.md +++ b/api-guidelines/rest/resources/naming-conventions/rules/must-use-camelcase-for-query-parameters.md @@ -4,12 +4,12 @@ id: R000022 # MUST use camelCase for query parameters -Use CamelCase to delimit combined words in query parameters. +Query parameters should be formatted in camelCase, and digits should be avoided. DO -`productId`, `articleNumber`, `loginId`, `lId` etc. +`productId`, `articleNumber`, `loginId`, `lId`, `entryDate` etc. DON'T -`product_id`, `Articlenumber`, `login-id`, `LID` +`product_id`, `Articlenumber`, `login-id`, `LID`, `1stDay` diff --git a/decisions/0003-should-avoid-digits-in-camel-case.md b/decisions/0003-should-avoid-digits-in-camel-case.md new file mode 100644 index 00000000..a5cd3257 --- /dev/null +++ b/decisions/0003-should-avoid-digits-in-camel-case.md @@ -0,0 +1,68 @@ +# [0003] Avoid digits in camel case + +- Status: `accepted` +- Decided by: , , , API Community, AsyncAPI Community +- Date: 2025-08-26 + +## Context + +Several rules in the OTTO API guidelines refer to using camel case for naming properties, parameters, and other identifiers in APIs. +The guidelines do not explicitly address the use of digits in camel case names, but our linter does not allow digits in camel case names. + +## Options + +### Option 1 + +Allow digits in camel case names, e.g. `item1`, `top100LoveSongs`, as there is no explicit rule against it. + +Example: + +```yaml +top100LoveSongs: + type: array + items: + type: string + description: The title of a love song. + example: + - "A Wonderful Song" + - "Another Awesome Love Song" + - ... +``` + +### Option 2 + +Do not allow digits in camel case names. + +Example: + +```yaml +popularLoveSongs: + type: array + description: Contains the 100 most popular love songs. + items: + type: string + description: The title of a love song. + minItems: 100 + maxItems: 100 + example: + - "A Wonderful Song" + - "Another Awesome Love Song" + - ... +``` + +## Decision + +Option 2 is chosen, as there is no known use case for digits in camel case names, and the OpenAPI specification provides features to describe ranges and array length if needed. +The linter rule is already in place and has been used in several APIs without issues. +This decision ensures more consistent naming conventions across all APIs and avoids potential compiling issues, if property names are starting with a digit, like in Java. + +## Consequences + +Existing guidelines referencing camel case names need to be updated to explicitly state that digits should be avoided. + +[rule-R000022]: ../api-guidelines/rest/resources/naming-conventions/rules/must-use-camelcase-for-query-parameters.md +[rule-R004010]: ../api-guidelines/global/json/naming-conventions/rules/should-use-camel-case-for-property-names.md + + + +