Common Data Types

Use common field names and semantics

APIs often expose similar data concepts across different resources. To ensure consistency between API implementations, common field names and their semantics should be used whenever applicable.

Using standardized field names improves API usability because client developers can build a common understanding of resources without needing to learn different naming conventions for similar concepts.

Generic fields

The following fields are commonly used in API resource models.

`id`

The identity of an object.

When used, IDs should follow these rules:

The ID must be an opaque string rather than a numeric value.
IDs must be unique within a documented scope.
IDs must remain stable after the object has been created.
IDs must never be reused for different objects.
IDs are often used directly in resource URIs.

Example:

text

GET /accounts/{accountId}

Since IDs are frequently used in URIs, the allowed characters should consider the restrictions defined by URI syntax.

Characters outside the URI allowed character set require encoding. Encoded IDs reduce readability and make troubleshooting more difficult.

Therefore, object IDs should preferably use URI-friendly formats.

For example, UUID is a suitable identifier format because it provides uniqueness while remaining compatible with URI usage.

`{objectType}Id`

When an object contains a reference to another object, the field name should represent the referenced object's type or relationship followed by Id.

Examples:

Preferred:

yaml

partnerId
parentNodeId
customerId

Avoid:

yaml

partnerNumber
parentNode
customerReference

The field name should describe the relationship, not the internal representation of the referenced object.

`createdAt`

Represents the creation time of an object.

If used, it must use the date-time format.

Example:

yaml

createdAt:
  type: string
  format: date-time

Example value:

text

2026-08-06T12:30:00Z

`modifiedAt`

Represents the last update time of an object.

If used, it must use the date-time format.

Example:

yaml

modifiedAt:
  type: string
  format: date-time

`type`

Represents the kind or category of an object.

If used:

The field type must be string.
Values should describe the runtime type of the resource.

Example:

yaml

type:
  type: string
  enum:
    - LEAF
    - NODE

The type field allows clients to understand the resource type without inspecting the complete API specification.

`ETag`

Represents the entity tag of an embedded sub-resource.

ETag values may be used to support conditional update operations such as:

PUT
PATCH

ETags help clients verify that the resource has not changed before applying updates.

Example:

http

If-Match: "abc123"

Example resource schema

yaml

TreeNode:
  type: object
  properties:
    id:
      description: Identifier of this node
      type: string

    createdAt:
      description: Creation timestamp of this node
      type: string
      format: date-time

    modifiedAt:
      description: Last modification timestamp of this node
      type: string
      format: date-time

    type:
      description: Type of this node
      type: string
      enum:
        - LEAF
        - NODE

    parentNodeId:
      description: Identifier of the parent node
      type: string

  example:
    id: "123435"
    createdAt: "2026-04-12T23:20:50.52Z"
    modifiedAt: "2026-04-12T23:20:50.52Z"
    type: "LEAF"
    parentNodeId: "534321"

These properties are not mandatory for every resource. However, using common naming conventions improves consistency and reduces unnecessary differences between APIs.

Link Relation Fields

To provide a consistent pagination experience, collection responses should use common link relation fields.

The following fields are recommended:

Field	Description
`self`	Link or cursor pointing to the current collection object or page
`first`	Link or cursor pointing to the first collection object or page
`prev`	Link or cursor pointing to the previous collection object or page
`next`	Link or cursor pointing to the next collection object or page
`last`	Link or cursor pointing to the last collection object or page

Pagination response fields

Pagination responses should contain an array field that carries the resources of the current page.

`items`

Contains the collection resources returned in the current page.

Example:

yaml

items:
  type: array
  items:
    type: object

The name items may be replaced with a more specific resource name when appropriate.

Example:

yaml

accounts:
  type: array
  items:
    $ref: "#/components/schemas/Account"

Query filters

To improve client usability, APIs may return the applied query filters.

`query`

Represents the filters applied when retrieving the collection.

Example:

yaml

query:
  type: object
  properties:
    status:
      type: string
    owner:
      type: string

Standard Pagination Response Example

yaml

ResponsePage:
  type: object

  properties:

    self:
      description: Link pointing to the current page
      type: string
      format: uri

    first:
      description: Link pointing to the first page
      type: string
      format: uri

    prev:
      description: Link pointing to the previous page
      type: string
      format: uri

    next:
      description: Link pointing to the next page
      type: string
      format: uri

    last:
      description: Link pointing to the last page
      type: string
      format: uri

    query:
      description: Query filters applied to the collection
      type: object

    items:
      description: Collection items of the current page
      type: array
      items:
        type: object

A pagination response may include additional metadata describing the collection or the current page.

Summary

Following common data type conventions provides:

Consistent API models across services.
Easier client development.
Reduced API learning cost.
Better interoperability between systems.
More predictable API evolution.

Common fields such as id, createdAt, modifiedAt, type, and pagination links should be reused consistently whenever their semantics apply.