Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add "const" for single value enums #1666

Closed
chatelao opened this issue Aug 16, 2018 · 14 comments
Closed

Add "const" for single value enums #1666

chatelao opened this issue Aug 16, 2018 · 14 comments

Comments

@chatelao
Copy link

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

Would be nice to include this

@silkentrance
Copy link

silkentrance commented Aug 16, 2018

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

@handrews
Copy link
Member

@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
Copy link

silkentrance commented Aug 16, 2018

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
Copy link
Member

@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
Copy link
Contributor

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
Copy link
Author

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
Copy link

@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
Copy link
Author

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
Copy link

silkentrance commented Sep 24, 2018

@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
Copy link
Member

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
Copy link
Contributor

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

@grische
Copy link

grische commented Aug 31, 2020

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

@handrews
Copy link
Member

@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
Copy link

grische commented Aug 31, 2020

Thanks for clarifying!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

7 participants