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.

[lieldulev]

@IvanGoncharov - good points,

• Based on http://json-schema.org/latest/json-schema-validation.html#anchor101 there are no restrictions on the value of default. If you think the name default itself is an issue - it is already part of the spec today so we should add it to Make schema object compatible with JSON Schema draft4 #333 anyway.
• I agree, if we provide a way for an evaluated value, we should have a fallback to an "hardcoded" one.
• I actually don't think this feature is a big deal for SDK generators - I might be mistaken, but most SDK can ignore this (using a hardcoded value will be wrong for that kind of parameter as well) and force users to pass the value.

I agree it has more value in interactive apis (like swagger ui) or generators for unit/load testing (where the actual call needs to have "good" values to be meaningful).

[fehguy]

I am on the side of @dilipkrish. This seems very specific to tooling and probably too complicated to have in the spec itself. For a vendor extension, the tooling provider would optionally support the construct.

[jharmn]

After exploring the possibilities and stewing on it a bit, I agree.

[Shulamite]

We have a requirement to indicate client whether a property has a default value or not. The client then can send the minimal set of data and exclude the ones with default value.
(We also have a resource that is used to return the default values. So if client wants to use the default value and allow users to change the default value, then they can do that too.)

[fehguy]

I'm going to tag this as a tooling consideration. Seems like some construct of extensions + tooling support can make for dynamic content. But it should likely stay out of the spec itself.

[webron]

Tackling PR: #741 (even though it may not get it, that's the point of consideration. The result of the PR may close this ticket as "not supported").

[ePaul]

I'm not sure such kind of "default" values are needed at all. Shouldn't the server be able to supply the value when it is missing? Why should this be provided by the client?

[webron]

As suspected, this did not make it into the spec, and it's marked as a potential tooling feature with the use of extensions.