Questions about Server Variable binding and defaults

[tedepstein]

I'm reading about Server Objects and Server Variables, and trying to understand how resolution/expansion is supposed to work.

The OpenAPI document can specify any number of servers, each with zero or more variables. Each variable can be an arbitrary string, or can be constrained to a string enum. Also, each variable MUST specify a default value.

Here are my questions:

• I guess one of the envisioned scenarios involves a service implementation that binds the server variables at runtime, according to the host, port, and path where the server is running. So it creates a new OpenAPI document with the variables resolved, and passes this to the client. Is that right?

• Another possible scenario is where the API consumer retrieves the original OpenAPI spec, with unbound variables, and dynamically resolves them with some known values. The client may have those server variable values supplied in a configuration file, or they may be provided by a human user at runtime. Correct?

• I don't see anything in the OpenAPI spec that tells us how variable resolution is expected to happen, or how it should be coordinated between the client and the OpenAPI document provider (which may or may not be the same as the server). I suppose the IANA-registered media type for OpenAPI documents, when we have one, could include a protocol for server variable binding in headers or query parameters, but I don't see any mention of this in the referenced issue. So, is it fair to say that server variable binding is entirely implementation-dependent?

• The default property of a Server Variable Object has this description in the spec:

  REQUIRED. The default value to use for substitution, and to send, if an alternate value is not supplied. Unlike the Schema Object's default, this value MUST be provided by the consumer.

  I don't understand what "by the consumer" means in this context, or maybe I'm just finding it confusing.

  • Is this just trying to say that each Server Variable MUST specify a default value? In that case it would not be the "consumer" who provides the default; it would be the OpenAPI document author or provider, right?
  • Or is it trying to say that if a value other than the default needs to be bound to the variable, then the "consumer" must provide that value? In that case it seems odd to say that consumer MUST do this, when there is no explicit mechanism specified for doing so. Maybe it would be a little more natural to say that it is up to the implementation, on the client side or the provider side, to substitute non-default values.

Any clarifications or comments appreciated.

[darrelmiller]

I don't really understand the first scenario you describe. The second one is how they are expected to be used and yes how the variable to value binding happens is implementation dependent.

"By the consumer" means by the user of the OpenAPI description. What this is trying to say is that if a URL looks like https://example.com/{v1}/ then the consumer of the API, can't just rely on the default value in the OpenAPI description and send a request to https://example.com/{v1}/ . The API consuming application must take the default value and replace the server variable before making the request. This is different than the behavior of defaults in JSON Schema.

[tedepstein]

@darrelmiller, thanks for explaining. IMO, the language in the spec can definitely benefit from some clarification and a bit of background introduction to illustrate the type of scenario for which server variables were intended.

When I can, I'll read through this carefully and suggest some more idiot-proof language.

I see that the language has changed in v3.0.3, but I still struggled to understand this.

Field Name	Type	Description
default	string	REQUIRED. The default value to use for substitution, which SHALL be sent if an alternate value is not supplied. Note this behavior is different than the Schema Object's treatment of default values, because in those cases parameter values are optional. If the enum is defined, the value SHOULD exist in the enum's values.

The first sentence, says the default value "SHALL be sent if an alternate value is not supplied." First, what does "sent" mean? Who is sending what value to whom, and what is the recipient of that sent value going to do with it? Would it be clearer (and is it accurate?) to say that the default value is assigned or substiuted into to the server variable in the absence of an explicit value?

The passive voice in the case where "...an alternative value is not supplied" begs the question of who might supply an alternative value. If I understand you correctly, the API client, a.k.a. consumer, has to substitute this value to get an actual server URL.

Most confusingly: We're saying that the default value SHALL be assigned (by someone) if an alternative value is not provided; and in the same breath, also saying that the API client MUST explicitly provide a value in all cases! So how could a situation arise where the variable has no value, and the default takes effect? 🤦‍♂️

OK, now that I've read your explanation, I think I understand that the default value is an instruction to the API client, effectively saying, "Since you are responsible for binding a value into this variable, you should use this default value unless you have special knowledge that a different value should be used." The client is still responsible for binding server variables; the default just gives a "dumb" or generic API client enough information to perform that binding without any external configuration or user input.

I hope I've got that right. Sorry to be thick, but this was not clear to me at all. And the language about how this is different from schema's default did not really do much to put me on the right track.

[tedepstein]

BTW, I realize (now) that all of this is much easier to grasp if you understand the use case. I am guessing this was designed for generic API testing tools, or dynamic documentation components like Swagger UI, where the default property allows the client to send requests to a default server, and enum allows the client to present options to the user. It all makes sense.

But if you missed the conversations (as I did) that provided this context, the specification of server variables can be hard to understand. At least it was for me. I'll submit suggestions soon.

[tedepstein]

Proposed clarifications in #2140.

[reitzig]

FWIW, this same issue has confused me today. I work in the use-case "SaaS and On-Premise" as listed on API Server and Base Path; sadly, there's no explanatory text at all.

In this scenario, are tools further down the chain expected to replace variables? For instance, I'm looking at inso generate config which doesn't seem to handle this at all.

If variables aren't intended to be used for deployment configuration, it may be worthwhile stating that very clearly. Ideally, with a reference to tools that fill that gap, if any.

[handrews]

@OAI/tsc review request: Does anyone have bandwidth to rework the old PR #2140 for 3.0.4/3.1.1? If not, should we bump this to 3.2.0? It does seem to have a practical impact we should address (see the most recent prior comment).

[lornajane]

This is covered by the work in #4062