Deals API 1.0 JSON Schema Unofficial

Decision records ·

D-002 How is a deal's created, startdate, and enddate written, when the text says "UTC timestamp in seconds in ISO-8601"?

Gap Cited on main and at the tag 1.0-202602.

What the schemas do

An RFC 3339 date-time in UTC, the ISO 8601 profile that JSON Schema's date-time format checks, such as 2026-11-02T00:00:00Z: its offset is zero, written Z, +00:00, or -00:00, and "in seconds" reads as precise to at least the second.

Options

  • utc-rfc3339 Chosen

    An RFC 3339 date-time in UTC, the ISO 8601 profile that JSON Schema's date-time format checks, such as 2026-11-02T00:00:00Z: its offset is zero, written Z, +00:00, or -00:00, and "in seconds" reads as precise to at least the second.

  • any-iso8601

    Any ISO 8601 representation of a UTC time, such as the basic format 20261102T000000Z or a week date, which no JSON Schema format checks.

  • epoch-seconds

    A count of seconds since the Unix epoch, written in the string the row types; OpenRTB 2.6 and AdCOM 1.0 count their timestamps in milliseconds instead.

Why

ISO 8601 writes a point in time in many forms, basic and extended, calendar, week, and ordinal dates, and at several precisions, and the text names none of them, so which form a deal writes is a point the text leaves open, as it is for OpenProposal's timestamps. RFC 3339 is the profile of ISO 8601 that JSON Schema's date-time format checks, and its UTC values are those whose offset is zero, so the schema accepts exactly them and rejects a value with any other offset, which the text's "UTC" excludes. "In seconds" next to ISO 8601, which a count of seconds isn't, reads as the precision: a date and a time to the second, which a fraction refines and doesn't contradict. Any ISO 8601 form would leave a receiver to parse every one of them; a count of seconds is no ISO 8601 value.

What we ask the specification to state

Say which form "UTC timestamp in seconds in ISO-8601" takes. ISO 8601 has several, and "in seconds" could be the precision or a count of seconds since the epoch, where OpenRTB 2.6 and AdCOM 1.0 count milliseconds. An RFC 3339 date-time in UTC, such as 2026-11-02T00:00:00Z, is the one JSON Schema checks.

The specification lines it rests on

Each line is quoted as the record pins it. Expand an item to read the quote.

main

  • Object: Deal, the created row L87 at 3028ddc
    created | string | UTC timestamp in seconds in ISO-8601 of when the deal was created in the Origin system
  • Object: Terms, the startdate row L108 at 3028ddc
    startdate | string | UTC timestamp in seconds in ISO-8601 of when the deal starts
  • Object: Terms, the enddate row L109 at 3028ddc
    enddate | string | UTC timestamp in seconds in ISO-8601 of when the deal ends. Evergreen or always on deals should leave this field blank.

Tag 1.0-202602

  • Object: Deal, the created row L87 at 938a5d1
    created | string | UTC timestamp in seconds in ISO-8601 of when the deal was created in the Origin system
  • Object: Terms, the startdate row L108 at 938a5d1
    startdate | string | UTC timestamp in seconds in ISO-8601 of when the deal starts
  • Object: Terms, the enddate row L109 at 938a5d1
    enddate | string | UTC timestamp in seconds in ISO-8601 of when the deal ends. Evergreen or always on deals should leave this field blank.

What it shapes

main: UtcTimestamp, Deal.created, Terms.enddate, Terms.startdate

Tag 1.0-202602: UtcTimestamp, Deal.created, Terms.enddate, Terms.startdate

The record's YAML file