Fields and Parameters

This section provides details on fields and parameters and the associated naming conventions and standards.

• Field and Parameter Definitions
• Objects and Arrays
• Field and Parameter Standards
• Field and Parameter Type and Format Standards
• Date & Time Fields
• ISO Fields
• Amount Fields
• Null Field Values

Field and Parameter Definitions

Fields are defined in OAS2 using the definitions object - an example is shown below where the name of the field is partyId. At OAS3 fields are defined in a similar manner.

definitions:
  partyId:
    description: The unique ID that identifies the Party.
    type: string
    minLength: 1
    maxLength: 10
    example: "PTY-005432"

Parameters are defined either against an operation in the paths object as per the OAS2 example below and they can also be defined as a parameter definitions object. At OAS3 parameters are defined in a similar manner.

parameters:
  partyId:
    name: partyId
    in: path
    required: true
    type: string
    minLength: 1
    maxLength: 10
    description: The unique ID that identifies the Party.

Objects and Arrays

Fields can be nested within objects (or arrays) as per the following OAS2 example:

  object1:
    type: object
    properties:
      object2:
        $ref: '#/definitions/object2'
  object2:
    type: object
    properties:
      string1:
        type: string
      string2:
        type: string

Whilst APIs support multiple nested fields, as per the above example, the use of $ref is mandated so that any individual structure does not contain more than two levels, hence, the following example would be deemed INVALID and should be refactored as per the above example:

  object1:
    type: object
    properties:
      object2:
        type: object
        properties:
          string1:
            type: string
          string2:
            type: string

Similarly, when using allOf, anyOf or oneOf, $ref must be used to reference allowed fields, for example, the following code shows both a valid and invalid definition:

# Valid structure       
FieldBlock:
  allOf:
    - $ref: '#/definitions/CommonFields'
    - $ref: '#/definitions/SpecificFields'
    
# Invalid structure - it should use a $ref instead of properties:
FieldBlock:
 allOf:
 - $ref: '#/definitions/CommonFields'
 - properties:
     field1:
       type: number
     field2:
       type: string 

The following lists the standards for defining structures:

Field and Parameter Standards

The following lists the standards for field and parameter names:

Field and Parameter Type and Format Standards

The following lists the standards for field types and formats:

Date & Time Fields

Date and time are defined by the OAS2 specification as RFC3339 which is a profile of ISO8601. Both OAS2 and OAS3 define date and time as a JSON string with a format defined by the JSON schema format extension.

The following table shows the mapping between the RFC and the JSON schema format extension. Note that time is not defined in the OAS2 specification but is accepted as an extension.

The following table shows the associated rules:

Example :

   fromDate:
    name: fromDate
    in: query
    description: First date of the date range. Date range can be up to 13 months
    required: true
    type: string
    format: date
    example : 2010-01-26

ISO Fields

ISO standards must be used for the following common business objects:

Amount Fields

The following is a snippets of an OAS2 definition for an amount field. This definition is recommended rather than mandated.

MonetaryAmount:
  type: object
  description: A monetary amount in a given currency supporting an amount format of 18.3 - a decimal point is expected for currencies that support them e.g. 1.00 GBP
  required:
    - amount
    - currency
  properties: 
    amount:
      type: string
      description: Amount
      pattern: '-?[0-9]{1,18}(\.[0-9]{1,3})?'
      example: '-5877.78'
    currency:
      description: ISO 4217 Alpha 3 currency code
      type: string
      pattern: '[A-Z]{3}'
      example: EUR

Null Field Values

The use of null as a field value in an API request or response must be avoided in most scenarios because null represents an unknown or undefined value and implies ambiguity.

For example: (1) the client should not need to send a request or receive a response using null unless using PATCH to remove a field value (2) the client or server can infer that a field value is null, i.e. undefined, if the payload does not contain the field key

The following table shows the associated rules: