restJson service serialisation behaviour for Timestamps

[codemedian]

Hi all.

I'm have a smithy service with the @restJson1 protocol that I generate an API GW spec and OpenApi based server/client stubs from. I'm currently looking at small stylistic issues that I'd like to address and one item that's on my list is inconsistent timestamp formatting. Based on the trait documentation the serialisation for JSON shapes uses epoch seconds in double fields which I can see in my generated spec.

Now to my question:

I use Timestamp fields both in query params, e.g. from field as well as in the response JSON payload, e.g. start and what I found is that

1. For the query param, the resulting OpenAPI takes in a date-time string with the OpenAPI spec looking like:

{
  "name": "from",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "date-time"
  },
  "required": true
}

2. For the response payload, which is a JSON shape, a Timestamp field gets serialised as

properties: {
  "start": {
    "type": "number",
    "format": "double"
  }
}

I would like my service to standardise on ISO_INSTANT for all, input as well as output timestamps.

Is the required as well as recommended approach to add an @timestampFormat trait to each and every operation and shape? This feels very error prone and can very easily lead to my standardisation efforts being ignored by a future change that simply forgets to add it.

Curious to hear thoughts/best practices to achieve what I'm trying to do

Thanks

[ianbotsf]

Hi @codemedian. Just to confirm my understanding, you want a way to default all timestamp formats in your restJson service model to a particular value (date-time)—is that correct?

If so, then I'm afraid there's no service-level or model-level mechanism to declare a default timestamp format. Instead, timestamp formats are resolved in this order (from most to least granular):

1. If present, the timestampFormat trait of the member:

   structure Foo {
       @timestampFormat("date-time")
       startDate: Timestamp
   }

2. If present, the timestampFormat trait of the target shape:

   structure Foo {
       startDate: Timestamp
   }
   
   @timestampFormat("date-time")
   timestamp Timestamp

3. The default format of the protocol (for restJson1, the default is epoch-seconds)

The easiest way to share a common format among all timestamps in your model is to declare a common timestamp shape with the desired @timestampFormat—option 2 in the list above. As long as all of your members target that shape, they will be serialized in the desired format.

A common timestamp shape may not be possible in cases where you need different constraints on different types. In that case, you could consider using a mixin to declare your single format and then apply that to all your unique timestamp shapes:

@mixin
@timestampFormat("date-time")
timestamp TimestampFormatMixin

@required
timestamp RequiredTimestamp with [ TimestampFormatMixin ]

@default("1985-04-12T23:20:50.52Z")
timestamp DefaultedTimestamp with [ TimestampFormatMixin ]

Neither of these two options (single common timestamp shape, multiple shapes with mixin) fully addresses your concern about standardization enforcement. The best way to address that is likely to add a model validator which flags members which do not use the correct format. See Smithy's documentation on model validation and model validation examples for more resources.

Does this answer your question?