need a way to specify non-const default field values (e.g.: current timestamp)

[mkrufky]

There currently is no standard way to specify a non-constant / computed value to be used as the default value of a field.

We have a few endpoints that take a timestamp as an argument. For the sake of our swagger documentation interacting with the most current data, we'd like this field to be pre-populated with the current timestamp, rather than a const value written in the swagger spec file.

Of course, we can hack the swagger UI somehow to treat certain specific fields differently, but I thought such a feature would be useful to others as well.

[lieldulev]

+1

I actually even have a case where the timestamp field's default value is a delta on the current time (UTC + 5 Minutes).

BTW, The field is defined as a number, since we pass unix epoch - like this one 1454942158.
The specific problem I have is that old timestamps will always return empty responses (the API has access to only a time based slice of the data, that keeps shifting forward).

[chrisferry]

👍

[jharmn]

Are there other use cases outside of timestamps for dynamic defaults you have in mind? This seems to open up a range of syntax we'd have to codify.
I'd also note this would need to support RFC3339 style dates in addition to UNIX timestamp format.

[lieldulev]

@jasonh-n-austin - I agree and I was actually thinking about it a lot, and after looking at default value expressions in Databases, I've categorized main 4 types:

1. Fixed value (Which is already supported)
2. Current Date/Time [+ Delta]
3. A transformation on another param (document_url = name.pathify())
4. Serial (counter)

I think (2) is not a lot of support and (obviously) needed, but I agree (3) can be, and we should not support it (right now).

I don't think (4) is a frequent use case for a REST API and I don't think we need it at all.

[mkrufky]

@jasonh-n-austin - Personally, I only need to be able to pass timestamps relative to now (+delta) as default arguments. I didn't have any other specific use cases in mind, but I thought it best to make this request as generic as possible. I'd agree with @lieldulev 's description of the four main types of possible default values. Supporting type (3) would be really nice, but what I am really asking for is type (2)

[jharmn]

Excellent point to look at database defaults @lieldulev.

To summarize requirements:

• Express dates and/or times in a variety of formats
• Increment/decrement current date/time by units of time (resolution of milliseconds to years?)

An obvious aspect of this would be a language-agnostic syntax for date expressions in the default field (sure seems like there would be some sort of standard for that). IMO the scariest part of this feature request is that we would essentially have code to calculate dates in the spec (maintaining syntax like this could easily snowball).

It would be really nice to have an existing syntax to work from; preferably something that already has existing specs & implementations. As I don't know of anything like this, the first thing that comes to mind is Excel syntax...?
http://www.excelfunctions.net/Excel-Date-And-Time-Functions.html

The other aspect to consider is a syntax for adding dynamically evaluation, something like:

"default": "{{ TODAY() }}" # double curlys delimit dynamic evaluation

[lieldulev]

@jasonh-n-austin, yep, nailed it.

• I like the duble curlys.
• There are multiple alternative's to the Excel list like
  • SQL's (https://msdn.microsoft.com/en-us/library/ms186724.aspx)
  • or Javascript's (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
  • or bash's date format support (http://ss64.com/bash/date.html)
  • or C (https://en.wikipedia.org/wiki/C_date_and_time_functions)
  • or python's (https://docs.python.org/2/library/datetime.html)

And while I'm sure we can find a hundred more - I would actually stick to either Excel or SQL:

1. A relative small subset of commands.
2. Well known.
3. A quick search found that there are enough ports out there like this one: https://github.com/sutoiku/formula.js/ that should make evaluating those expressions less painful in code generators.

[jharmn]

Definitely not liking any of the alternatives, as they are all pretty language or vendor specific. ANSI SQL might have some value, but it just seems odd to use database syntax in an API definition (not that Excel really feels right either).

Playing with Excel formulas more, it's pretty gross in practice, when it comes to formatting dates.

Examples:

# DATE
# Today, Epoch
(TODAY()-DATE(1970,1,1))*86400
# Tomorrow, Epoch
(TODAY()+1-DATE(1970,1,1))*86400
# Today, ISO8601
TEXT(TODAY(), "YYYY-MM-DD")
# Tomorrow, Epoch
TEXT(TODAY()+1, "YYYY-MM-DD")

# TIME
# One hour forward, Epoch
(NOW()+TIME(1,0,0)-DATE(1970,1,1))*86400
# One hour forward, ISO8601
TEXT(NOW()+TIME(1,0,0), "YYYY-MM-DD HH:MM:SS") # There seems to be no specific provision for timezone

Seems like something more date format friendly would be nice. This issue is tricky when it comes to the syntax piece.

[lieldulev]

I agree, picking syntax is a big problem since it might affect other decisions down the road.

How about we allow tagging the language? Something like {{[lang]:

"default": "{{excel: TODAY() }}" # double curlys delimit dynamic evaluation

or maybe using the {{=[lang]:

"default": "{{=js: new Date() }}" # double curlys delimit dynamic evaluation

Both languages will be "valid" but one of them might not be supported by all generators.

[webron]

I'd suggest if we go ahead and try to resolve this issue, that we keep it simple. We definitely shouldn't allow for something that's more language-specific, that would be a tooling nightmare. We can go with some basic construct of our own, even if it doesn't cover all cases.

[lieldulev]

👍 for @webron being the voice of reason while I am getting carried away :)

[IvanGoncharov]

couple things to consider:

• default field is inherited from JSON Schema so if you change it meaning it will add up to Make schema object compatible with JSON Schema draft4 #333
• If you want to handle some magic values, you need to provide escaping mechanism to allow puting such values 'as is'.
• SDK generation became more complicated and at the same time SDK usage. Because execution environment affects result of the call.

I think only good usage scenario for such field is interactive documentation.
So it make sense to do it as separate field and don't affect other tooling.

[dilipkrish]

My 2 cents. It seems like this is a great candidate to leave as a vendor extension with specific conventions. A curated spec-contrib with explicit guidance, but not part of the spec.