Specify custom query parameter format


I would like to define a query parameter of type “number” with the format “date-time” in the Stoplight GUI editor.

This works fine for model properties, but not for query parameters.
Only when I choose type “string” I can select “date-time”. I can not add custom formats here as for model properties.

I am doing that because we generate a Java API from that and we need to know that this timestamp should be generated as java.util.Date but serialized as number timestamp.

Any official option how to do that?


Hi @alexander.pehm!

According to OpenAPI, query parameters are required to have a type. This is why you may notice you have to select a type before you can select a custom format like date-time.

It’s not the most enjoyable reading, but you can read more here:

Specifically the table where: If [ in ] is any value other than "body":

The specification itself also specifies that date-time is to be a string. So it doesn’t give us a lot of wiggle room on this one.

Has your API already been implemented?

Hi @taylor,

thanks for your feedback.

Yes, I understand that a type is required before you can have a format, and the format date-time actually needs type string.

As workaround I manually wrote type=number, format=date-time into the query parameter in the specification and adopted our code generator to generate from that config a util.Date as Java type.

But as this is not standard conform: Do you have a suggestion how I could configure a parameter as type=number without having format=date-time and nevertheless know in my consuming generator that for this parameter util.Date is expected to be generated?

Your workaround is likely the best option for you right now since there aren’t really any valid options for configuring a parameter like this.

Heads up: The workaround itself won’t be valid JSON Schema because the ‘date-time’ format is supposed to be a RFC3339 formatted timestamp, which is based on the JSON Schema specification itself. You can still leave it as is though for documentation purposes, but you will want to keep this in mind if you run it through other validation or linting tooling.

1 Like