Enforce integer `modified` date and afterTimestamp as MUSTs.

[nickevansuk]

Proposer

ODI

Use Case

Make RPDE easier to consume by enforcing integer modified date and afterTimestamp. Allowing modified to be either string or integer causes issues when using the modified date for cache invalidation, as both cases must be considered in the data store and application layer.

Proposal

Enforce integer modified date and afterTimestamp as MUSTs.

Examples

{
  "next": "http://api.letsride.co.uk/public/v1/rides?afterTimestamp=1453931925&afterId=2710",
  "items": [
    {
      "state": "updated",
      "id": 2710,
      "kind": "event",
      "modified": 1453931925,
      "data": {}
    }
  ],
  "license": "https://creativecommons.org/licenses/by/4.0/"
}

[nickevansuk]

Now depends on https://github.com/openactive/opportunity-api/issues/10

[lukehesluke]

@nickevansuk are you aware of any implementations that use strings for modified (discounting cases where the string is something like "1234" which should actually be an integer)? Perhaps someone puts dates (e.g. ISO-8601) in here?

[nickevansuk]

Although the 1.0 spec does support both, we have been strongly encouraging implementations to converge on integer modified values, pending the next spec version which will include this change, to make data consumption easier for data users.

The libraries only support integer:

• https://github.com/openactive/models-php/blob/45ceb5eba21cf432777673ca0164ca0e6a5409f9/src/Rpde/RpdeItem.php#L26-L34

• https://github.com/openactive/models-ruby/blob/21031c18220a9cd718ae0ff2205081a2a801d685/lib/openactive/rpde/rpde_item.rb#L6C2-L7

• https://github.com/openactive/OpenActive.NET/blob/ce2a439e5564b54264939b712d2cfc4bd95b7e6a/OpenActive.NET/rpde/RDPEModels.cs#L50-L53

And the RPDE validator will return a warning to encourage integer to be used:

• https://github.com/openactive/rpde-validator/blob/0a4fc0e19e98dc083d7ee00a76f9ed2890b55ce3/src/rules/page/after-timestamp-rule.js#L33-L39

The model validator still allows strings (however could easily be updated so that it does not):

• https://github.com/openactive/data-models/blob/4052735e8ab405c11dcf6b045b666038473da2ca/versions/2.x/rpde/FeedItem.json#L63-L66

I believe British Cycling (the first ever RPDE implementation) was the only implementation to have adopted a string, however as this thread shows, they quickly moved to the integer approach based on implementation feedback. Since then I don't believe any other implementations have made use of a string for this purpose.

I think it's safe to assume that this will be included in the next version of the RPDE spec given all of the above, and so implementers can assume that modified is an integer for all implementations.