Standard Data Items/Terms/Attributes and Standard Suffixes

Time Stamps

All date-time values accepted or returned from APIs MUST be specified in the “complete representation” specified by ISO 8601 (section 4.3.2 in the official ISO-8601 spec) and conform to the syntax described in RFC 3339 Section 5.6. Date-time values without a zone designator or offset MUST NOT be used.

• Valid: 1985-04-12T10:15:32Z
• Valid: 1985-04-12T10:15:32+04:00
• Invalid: 1985-04-12T10:15:32 (no time zone designator or offset)

Time Ranges

For a time range, the start of the range is inclusive and the end of the range is exclusive.

In mathematical terms, a range includes time greater than or equal to the start of the range and less than the end of the range (timemin <= t < timemax). For example, a time range of 12:00:00 to 13:00:00 would include items with time stamps of 12:00:00 but would not include items with time stamps of 13:00:00.

The format of date/time ranges conforms to ISO 8601.

For example, a range of

2013-01-14T00:00:00Z/2013-01-15T00:00:00Z

includes all times from and including 00:00 on January 14th up to but excluding 00:00 January 15th.

For more information on why time ranges are specified this way, see Background on Time Ranges.

Distances

“Distance” as a stand-alone term is ambiguous. Any data that contains a distance value MUST be disambiguated by doing the following:

• Define what the distance is
• Define what the distance is between (start and end points)

Examples:

• Invalid: “distanceToJob”, “maxDistance” (don’t specify start and end points)
• Valid: “distanceOfficeToJob”, “distanceOfficeToJobMax” (as long as they are in a context where Office and Job are clearly-defined locations)

This disambiguation applies to all fields, parameters and values in all APIs.

All distances MUST be represented as floating point numbers.

All distance fields MUST qualify the distance end point of the measurement spatially or temporally (e.g., “distanceToJob”, “odometerCurrent”).

All distance fields MAY omit qualifying the distance start point if it can be inferred from the spatial or temporal context of the record the field is attached to (a vehicle’s current position in the case of “distanceToJob”, or from the time of vehicle manufacture in the case of “odometerCurrent”).

Angles

Angles SHOULD be represented in decimal degrees, following the appropriate (nonexhaustive) origin and turning sense for the angle type:

By default, heading, bearing, and course angles refer to degrees on the horizontal plane. Since angles can be used for the vertical plane, APIs requiring them MUST distinguish between the horizontal and vertical planes. For example:

{
   "speed": 112.4,
   "heading": 225.12,
   ...
}
—————————————————————————————————————————
{
   "speed": 566.7,
   "horizontalBearing": 67.9,
   "verticalBearing": 11.4,
   ...
}

Durations

Durations express an amount of elapsed time. They can be running durations (e.g. “it’s been 32.2 seconds since the job started”) or completed durations (e.g. “it took this long to process the job”).

When expressed in an API, durations SHOULD provide enough information to the client to make sense of them. This means a duration:

• Expresses the subject of the duration (e.g. a batch processing job). This can be done either in the field name or in the context of the object in which the duration is included. In either case, it SHOULD be evident to the client which field contains the duration.
• In the event a non-standard unit of measure is required (e.g. nanoseconds), the field MUST express the unit of measure in the name of the duration field
• Provides a meaningful value for both the subject and unit of measure

Durations MUST be represented as a non-negative floating point or integral number depending on the duration precision required.

The following examples show valid durations:

{
   "jobName": "Message Report ETL",
   "jobId": "abcdefgh-ijkl-mnop-qrst-uvwxyz012345",
   "duration": 347.32
}
——————————————————————————————————————————————————
{
   "report": {
      "name": "Driver Scorecard",
      "createdBy": "John Q Safety Manager",
      "durationMilliseconds": 477,
      …
   }
}
——————————————————————————————————————————————————
{
   "antimatterContainmentSystem": {
      "fuelLevel": 47,
      "fieldStrength": 32.6,
      "timeSinceRepolarizationMinutes": 42.5
   }
}
——————————————————————————————————————————————————
{
   "warrantyPeriodMonths": 12
}