Add "const" for single value enums

[chatelao]

JSON-Schema supports "const" for single value enums.

Would be nice to include this

[silkentrance]

Enums are always considered to be const. Cannot imagine why they add this redundancy over at JSON schema.

[handrews]

@chatelao OpenAPI will get const when it updates to newer drafts of JSON Schema.

In the near-ish future, this will be possible with the x-oas-draft-alternativeSchema proposal (see #1532)

[silkentrance]

Considering https://ajv.js.org/keywords.html#const, why? If it is constant, then it is already known by both the client and the server. No need to transfer or even validate the same data over and over again. Of course, the code generators might be able to optimise this, but this poses a lot of extra work on the framework. And IMO this is actually counter productive against reducing overall latency and load on both client and server.

[handrews]

@silkentrance you seem to only think of OpenAPI and JSON Schema in terms of code generation, when they are used for quite a bit more than that. JSON Schema in particular has many applications completely outside of either code generation or APIs.

Within the context of an API, an application that wants to avoid transferring a redundant value should use default to document the behavior that occurs when the field is omitted. Which can be used with const or with any other set of validation assertions.

[tedepstein]

I think const can be useful as a discriminator in complex type hierarchies.

OpenAPI already extends JSON Schema by allowing a single discriminator property, which works to describe a statically defined, single-classification hierarchy.

But there are cases where classification may be dynamic, and/or may have multiple dimensions. For example, a financial instrument may be debt or equity, exchange-traded or OTC, corporate or government-issued. Simplifying quite a bit here, but let’s say these classifications can exist in any combination. If we want to specify that a given request or response requires an exchange-traded corporate debt instrument, we could define an object schema just for that purpose, but this requires clients and servers to converse in a specialized set of classes for each specific case, and the multi-dimensional classification matrix does not map neatly to most type systems.

So in this case, specifying a more general FinancialInstrument as the type, and adding const assertions for the discriminating properties (debtOrEquity, exchange, issuerType) might be preferable.

[chatelao]

Exactly, I have a complex type with an IBAN and as another option "all" as a constant.

Using "enum" is not a big deal, but "const" would just be nice.

[silkentrance]

@chatelao Could you provide me with a pointer to the complex type, please? I am just curious on how it is realised and whether one could achieve the same functionality in a different way, if there is one.

[chatelao]

components:
  parameters:
    iban_all_tmpl:
      name: iban
      in: path
      description: 
        all oder die Interantional Bank Account Number (IBAN) eines Kontos
      required: true
      explode: true
      schema:
        oneOf:
          - type: string
            enum: [ all ]
          - $ref: '#/components/schemas/iban'


  schemas:
    iban:
      title: Kontonummer IBAN (International Banking Account Number)
      type: string
      example: CH0309000000250090342

[silkentrance]

@chatelao so basically you want to coalesce the two use cases

1. list all IBANs
2. get one IBAN

into one.

Maybe defining iban as a pattern, e.g.

iban:
  pattern: ^(all|...)$

would do the trick? Not to mention that I see two different use cases and therefore two different end points here... One that configures the backend lookup with a specific query and one that configures it so that it will return all IBANs from the persistent storage, possibly also providing for paging and whatnot.

[handrews]

This is a duplicate of #1313

As I noted there:

JSON Schema 2019-09 (formerly known as draft-08) has now been published.

PR #1977 in this repository updates OpenAPI's Schema Object for OAS 3.1 to use JSON Schema 2019-09, which includes the const keyword (added back in draft-06). Assuming that PR is eventually accepted, it will solve this problem in OAS 3.1.

[philsturgeon]

You got it, #1977 is merged so we can close this.

[grische]

@darrelmiller @philsturgeon it seems the changes have been reverted by #2124 and there is no mention of const anymore. Was this intentional?

[handrews]

@grische since OAS is now fully compatible with JSON Schema, there is no need to explicitly list JSON Schema keywords in the specification. const (and everything else in the JSON Schema Core and Validation specs) is supported in 3.1.

[grische]

Thanks for clarifying!