Skip to content

Naming & Formatting

Guidance

  • Fields should use camelCase.
  • Acronyms should be camelCase rather than uppercase.
  • Abbreviations should be avoided.
  • Booleans should be prefixed with an auxiliary verb (such as is, has, or can).
  • Enums should be UPPER_CASE strings with underscores in place of spaces.

Case

The VA recommends using camelCase rather than snake_case or kebab-case for JSON field names. API teams can use any programming language for their applications, including C-style languages (Ruby, Python, etc.) whose style guides/communities have decided on snake case for variable and field names. That said, being consistent across the VA set of APIs is necessary. Camel case is chosen since JavaScript is the dominant language for web clients/API consumers (and is the JS in JSON), and it uses camel case.

Acronyms

Acronyms are usually written in uppercase within API documentation while most programming languages reserve uppercase for constants. Using uppercase for the acronym name within a field that follows the camel case naming convention can be confusing when read by consumers. For example, the field named BIRLSId contains an acronym but it's difficult to tell where the acronym name ends and where the next part of the variable name begins. Therefore, name your field birlsId instead of BIRLSId.

Abbreviations

For clarity, it's better to spell a word completely rather than use an abbreviation, especially a non-standard one. Modern editors and IDEs can autocomplete variable names, so abbreviations no longer save keystrokes. The VA has complicated terminology; future developers or your future self will appreciate the lack of ambiguity.

Booleans

JSON is not typed, so prefixing boolean fields with an auxiliary verb (such as is, has, or can) marks it as a boolean field. This is also closer to natural language, e.g., run this code if the user is a veteran becomes if (isVeteran) {}.