OpenAPI Standards

Our APIs conform to OpenAPI standards

We follow OpenAPI Specification v3.1.0 - the official documentation is here

There is also good documentation on the swagger.io website - note these are for v3.1.1 but the differences are mostly in docs and explanations - see the release notes

OpenAPI standards rely on the JSON Schema standards for many specific details like data types.

For clarity we are providing some specific impacts of these standards on this page, mostly relating to data formats

Numeric data formats

There are two kinds of numbers in an OpenAPI schema:

• Integers: type: integer
• Numbers: type: number

As stated in the spec:

Note that the type keyword allows "integer" as a value for convenience, but keyword and format applicability does not recognize integers as being of a distinct JSON type from other numbers because JSON itself does not make that distinction. Since there is no distinct JSON integer type, JSON Schema defines integers mathematically. This means that both 1 and 1.0 are equivalent, and are both considered to be integers.

Valid integers

• 0
• 1.00
• -1234
• 65536

Note that an integer may have trailing decimal places such as 1.0 or 1.00 and so on - these are treated as equivalent to 1 in JSON.

Valid numbers

Numbers can be both integers and floating point numbers - these are all valid number types:

• 123.456
• -123.4560
• 123
• 123.00
• 123.11

Note as mentioned above that 123 and 123.00 should be treated identically, as decimal numbers.

Format specifiers

A number can have an optional format specifier - these are just hints not formal rules. For instance we may specify:

amount:
  type: number
  format: float

This indicates that the amount is a floating point number and should be stored in an appropriate data type.

We Strongly recommend using a Decimal data type for any non-trivial handling of numeric values - such as C#'s Decimal type, or Java's BigDecimal, or the Big.js JavaScript library (there is also an active proposal to add Decimal types to JavaScript which could be used when available)

Validation rules

We may in some cases supply validation rules such as minimum or maximum - we encourage checking the official documentation if these are unclear.

Dates and Times

Dates and Date-Time values are a specific format of Strings:

StartDate:
  type: string
  format: date-time
  example: '2025-02-01T12:01:02-05:00'

Date-times

The OpenAPI specification is quite strict about valid date-times, using RFC 3339, section 5.6 which is a subset of ISO8601:

• They must be UTC or specify a numeric offset from UTC. Justification is in the RFC3339 spec.
  • So they must end with Z for UTC, or +HH:MM or -HH:MM for offsets from UTC
• They must have a full numeric year, month, day, hour, minute and second value. (ISO8601 makes some of these optional)
• They may optionally have a fractional number of seconds

Valid DateTimes:

• 1985-04-12T23:20:50.52Z
• 1996-12-19T16:39:57-08:00
• 2025-07-30T11:07:23.229499+00:00

Dates

Dates are much simpler as they only have the date component and no time nor time-zone:

• 1985-04-12

Implications to users of Liberis APIs

Our APIs may produce DateTimes in any of the above valid formats - you should not rely on examples matching exactly what we send. For instance fractional seconds may or may not be provided, and UTC offsets may be a Z suffix or a numeric +00:00.

We will expect to receive dates and date-times in these formats. Our APIs may accept local date times in payloads, as we attempt to be lenient in data formats we can parse; but this is invalid data and may result in undefined behaviour.

There may be specific exceptions - in some cases we may have exceptions to support legacy APIs - in these cases we will note the exception in our documentation.