[ADP-701] Attribute Design

Guidance

• Attributes MUST use camelCase naming convention.

TIP

See Design Consideration below

• Field names MUST be ASCII alpha num characters, underscore (_) or dollar sign ($).
• Attributes SHOULD NOT use special characters such as : [ ] . ; %.
• Attribute names SHOULD be clear, concise, and self-descriptive.
• Attribute names SHOULD use full words instead of abbreviations, unless the abbreviation is more commonly used than the full word.
  • Specific domain abbreviations that are not widely known SHOULD NOT be used; see reference materials.
• Bool attributes SHOULD use prefixes like "is", "has", or "can" (e.g., "isActive", "hasPermission", "canEdit").
• Attributes representing collections SHOULD use plural nouns (e.g., "users", "items", "orderLines").

Design Considerations

There are two common naming conventions for JSON attributes:

1. camelCase
2. snake_case

Although some companies/organizations use snake_case to match query parameter conventions (like underline_snakecase), it is not intuitive. Therefore, we choose to use camelCase for naming JSON attributes to maintain consistency and readability.

TIP

💡 When attributes need to be included in a URL, convert camelCase to kebab-case to comply with our path naming conventions.

Examples

Basic Property Naming

{
  "userName": "johnDoe",
  "emailAddress": "john@example.com",
  "isActive": true,
  "hasSubscription": false,
  "orderItems": [
    {
      "productId": "12345",
      "quantity": 2
    }
  ]
}

Query Parameter Example

GET /users?filter.userName=johnDoe&filter.emailAddress=john@example.com HTTP/1.1

URL Path Example

GET /users HTTP/1.1

HTTP/1.1 200 OK

{
  users: [
    {
      registeredApplications: []
    }
  ]
}

Let's say we have registeredApplications as property of the user schema; when we need to apply the property in uri it needs to be transformed into kebab-case.

GET /registered-applications HTTP/1.1

References

Design References: Abbreviation Naming Conventions

• Google API Design Naming Conventions
• Swift API Design Guidelines
• Watson Developer Cloud API Guidelines
• ADIDAS API - JSON

Changelog

• 2024.11.04: Add field name limit