[ADP-764] OpenAPI format conventions

Overview

OpenAPI Schema and JSON Schema

OpenAPI Schema: The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for RESTful APIs, which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

JSON Schema: JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. It is used to describe the structure and validation constraints of JSON data. JSON Schema can be used for a variety of applications, such as data validation, documentation, and contract testing.

Formats in OpenAPI Schema: Formats in OpenAPI Schema provide a way to specify more detailed constraints on data types. These formats can help ensure that the data being processed matches the expected patterns, which can be essential for validation and interoperability. The OpenAPI Specification uses JSON Schema for defining the data types and structures used in API requests and responses.

Guidance

The API document SHOULD define the format of a payload's field with standard OpenAPI format or a new format with JSON schema.
When using custom formats, they SHOULD be clearly documented in the API specification.
Developers SHOULD use the most appropriate format for each data type to ensure accurate data representation and validation.
When extending or creating new formats, developers SHOULD follow the principles outlined in ADP-754: OpenAPI JSON Schema.

Format Table

Here is an introduction to some of the common formats used in OpenAPI schema:

Data Type	Format	Description	Standard
string	date	Date value in RFC 3339 format (e.g., "2024-07-08")	RFC 3339
string	date-time	Date and time in RFC 3339 format (e.g., "2024-07-08T14:30:00Z")	RFC 3339
string	duration	Duration in ISO 8601 format (e.g., "PT2H")	ISO 8601
string	password	A hint to UIs to obscure input	N/A
string	byte	Base64-encoded characters	RFC 4648
string	binary	Any sequence of octets (usually a file)	N/A
string	email	An email address (e.g., "mailto:example@example.com")	RFC 5322
string	uuid	A universally unique identifier (UUID)	RFC 4122
string	hostname	A valid hostname as defined by RFC 1123	RFC 1123
string	ipv4	An IPv4 address (e.g., "192.168.1.1")	RFC 791
string	ipv6	An IPv6 address (e.g., "2001:0db8:85a3:0000:0000:8a2e:0370:7334")	RFC 8200
string	uri	A URI (e.g., "http://example.com/")	RFC 3986
string	uri-reference	A URI reference (e.g., "/relative/path")	RFC 3986
string	uri-template	A URI template (e.g., "http://example.com/{id}")	RFC 6570
string	json-pointer	A JSON Pointer (e.g., "/pointer/to/something")	RFC 6901
string	regex	Regular expressions as defined in ECMA-262	ECMA-262
number	float	Single-precision floating-point number	IEEE 754
number	double	Double-precision floating-point number	IEEE 754
integer	int32	32-bit integer	N/A
integer	int64	64-bit integer	N/A

Custom Formats

When defining custom formats, follow these guidelines:

Use clear and descriptive names for custom formats.
Document the format pattern or constraints thoroughly.
Provide examples of valid and invalid values.
Consider using regex patterns to define the format when applicable.
Ensure that custom formats do not conflict with existing standard formats.

Example of a custom format definition:

yaml

components:
  schemas:
    CustomFormat:
      type: string
      format: custom-phone-number
      description: A custom phone number format (e.g., +1-555-123-4567)
      pattern: '^\+\d{1,3}-\d{3}-\d{3}-\d{4}$'
      example: '+1-555-123-4567'

[ADP-764] OpenAPI format conventions ​

Overview ​

OpenAPI Schema and JSON Schema ​

Guidance ​

Format Table ​

Custom Formats ​

Related ADPs ​

References ​