Data formats and values

This document describes how to format the data that you return from a connector or use in default values in the connector configuration. An example is given for each logical type.

SINGLE_LINE_STRING

Single-line strings can be up to 250 bytes long, and can be further limited by the schema.

"This is a single-line string."

MULTIPLE_LINE_STRING

Multiple-line strings can be up to 32K bytes long, and can be further limited by the schema.

"This is a multiple-line string."

DATE

Date values must be in the ISO 8601 format "YYYY-MM-DD". Also, values must be in the range from 1753-01-01 to 9999-12-30.

"2021-11-30"

TIME

Time values must be in the ISO 8601 format "hh:mm:ss". Seconds are optional, but hours and minutes are not. Greater precision than seconds is not supported.

"23:59:59"

DATE_AND_TIME

Four pieces of information are required to specify a particular point in time:

• The date
• The time as it would appear on a clock
• The time zone in which the point in time is observed
• If the point in time occurs during the hour that is repeated when clocks are turned back to end Daylight Saving Time, whether to use the first or second occurrence of this time.

There are two ways to return values with the DATE_AND_TIME logical type. You can use an ISO 8601 string without a time zone, or a date-and-time JSON object that explicitly defines the time zone.

When you use the ISO 8601 format, the time zone is taken from the timeZoneId that's defined in defaultValues in the connector configuration. If no default is present, the time zone is set to UTC.

"2021-12-30T23:59:59"

or

"2021-12-30T23:59:59.999"

When you use a date-and-time JSON object, a DATE_AND_TIME value looks like this:

{
  "localDateAndTime": "2021-12-30T23:59:59.999",
  "isDST": false,
  "timeZoneId": "Europe/London"
}

Here, localDateAndTime is a timestamp string that conforms to ISO 8601 as above; timeZoneId is an identifier from the IANA Time Zone Database that specifies the time zone in which the moment of time was observed; and isDST specifies which occurence of the repeated hour to use - true for the first, false for the second.

BOOLEAN

Boolean values must be be either true or false.

true

or

false

INTEGER

Integer values must be in the range from -2147483648 to 2147483647.

2147483647

DOUBLE

Double values must be in the range from 4.94065645841246544e-324 to 1.79769313486231570e+308.

4.94065645841246544e-324

DECIMAL

Decimal values are represented as a string, can contain up to 18 digits before the decimal separator, and up to 4 digits after it. There can be a leading minus sign, but no exponent (e) notation.

"-123456789012345678.1234"

SELECTED_FROM

Selected-from string values must match a permitted value that the schema or a form condition defines.

"This is a selected-from string."

SUGGESTED_FROM

Suggested-from string values must match a permitted value that a form condition defines when you use them as default values, but are otherwise unrestricted.

"This is a suggested-from string."

GEOSPATIAL

Geospatial values must be formatted as GeoJSON points, as described at https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.2.

The first element in the coordinates array is longitude, and must be a number between -180.0 and 180.0. The second element is latitude and must be a number between -90.0 and 90.0.

{
  "type": "Point",
  "coordinates": [1.0, 2.0]
}

GEOSPATIAL_AREA

Important: Values of type GEOSPATIAL_AREA are valid for use in connector configuration, but not in the data that you return from a connector.

Geospatial area values must be formatted as GeoJSON feature collections, as described at https://datatracker.ietf.org/doc/html/rfc7946#section-3.3. Foreign members are allowed.

The geometry must be of type Polygon or MultiPolygon, both of which must contain at least four coordinates, where the first coordinate matches the last.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
          [
            [
              [1.0, 2.0],
              [3.0, 4.0],
              [5.0, 6.0],
              [1.0, 2.0]
            ]
          ]
        ]
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [1.0, 2.0],
            [3.0, 4.0],
            [5.0, 6.0],
            [1.0, 2.0]
          ]
        ]
      }
    }
  ]
}