SolvedOpenAPI Specification Defining constant value in response

In order to specify that the response for an API call is always a certain given value, I would like to create this this feature request.

If the client wants to get the details of a non-existing pet of a pet store then the server should say

{
    "status": "ERROR",
    "error_message": "ERROR__PET_NOT_FOUND"
}

The best way I found for describing this is to use enums with only one element, like this:

    schema:
        type: object
        properties:
            result: 
                type: string
                enum: [ERROR]
            error_code: 
                type: string
                enum: [ERROR__PET_NOT_FOUND]

Instead of this, an exact value should be defined with an implicit type detection. So,

    schema:
        type: object
        properties:
            result: 
                value: "ERROR"
            error_code: 
                value: "ERROR__PET_NOT_FOUND"

should mean the same as the previous declaration.
The following scalar types should be auto-detected:

• type = string, if the value is surrounded by " symbols
• type = integer, if the value contains only digits and sign
• type = float, if the value contains digits, sign AND decimal point

Moreover, the new value declaration should work one level above as well:

    schema:
        type: object
        properties:
            value: 
                result: "ERROR"
                error_code: "ERROR__PET_NOT_FOUND"

This specification should mean a structure that has the two fields with these two constant values.

One more step would be the following notation:

    schema:
        value: 
            result: "ERROR"
            error_code: "ERROR__PET_NOT_FOUND"

This would determine the type to be an objects and the properties as above.

This notation would be much more dense and easier to both write and understand.

Having a constant could be interesting for the Inheritance and Polymorphism case (when a discriminator and a mapping are defined in a oneOf schema). Take this example from the guide:

components:
  responses:
    sampleObjectResponse:
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/Object1'
              - $ref: '#/components/schemas/Object2'
            discriminator:
              propertyName: objectType
              mapping:
                obj1: '#/components/schemas/Object1'
		obj2: '#/components/schemas/Object2'
  …
  schemas:
    Object1:
      type: object
      required:
        - objectType
      properties:
        objectType:
          type: string
      …
    Object2:
      type: object
      required:
        - objectType
      properties:
        objectType:
          type: string
      …

In this case, objectType defined in #/components/schemas/Object1 and in #/components/schemas/Object2 is just present for the discriminator mapping, it would be much nicer to have it defined as constant.

@gvdmarck 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.

@halmai Taking my OAI hat off for the moment, because this is purely a personal opinion. Also, this comment isn't directed specifically at you, it is just that your assertion reflects a common belief that I feel needs to be addressed.

You said,

it makes the client development easier because the client doesn't have to interpret all the http status codes

I believe that this is incorrect. Moving the error description into the response body "for consistency" does help map HTTP APIs to a client side RPC signature. It allows HTTP APIs to be presented in a way that client developers are more familiar with. However, it is definitely not easier than using the HTTP status codes as they were intended to be used.

In your example, you already know that the response is a 404. Having a client understand that HTTP Status code 404 means "not found" is not only simple, it is consistent across all HTTP API implementations. Requiring a client developer to have to read a payload of some media type, that has some custom error payload structure, that then has some custom enum that repeats the error "not found" is not easier.

Client libraries do not have to interpret ALL of the HTTP status codes. It needs to understand 200, 300, 400, and 500 plus optionally any extra codes that the client wants to do special handling for. The HTTP spec says that if you receive a status code that you don't understand, round it down to the nearest hundred and treat it as that.

It can be useful to have payloads for response bodies that have additional details. However, there is a standard for that https://tools.ietf.org/html/rfc7807 which has existing implementations. These things should not be reinvented over and over again.

Finally, your original request was the ability to define a schema for a constant value. OpenAPI bases it's schema on JSON Schema, and JSON schema doesn't support what you are trying to do. If you want JSON Schema to change, then I would suggest talking to them, we don't have that authority.

Is there any update on this ? If you want a clear use-case, just think json:api :

GET /articles/

response:

{
  "data": [
    {
    "type": "articles",
    "id": "1",
    ...
   },
   {
    "type": "articles",
    "id": "2",
    ...
   },
   {
    "type": "articles",
    "id": "3",
    ...
   }, ...]
}

The current workaround (enum with one value) is so hacky I don't understand how it is sufficient/reasonable for everyone.

I'd like to register my interest in what @halmai originally requested. My use case is that in our responses there are some generic properties for making the response a bit more self-describing. For example, every response has a "kind" property that allows identifying what kind of stuff it contains.

We currently follow what @halmai found, namely to define an enum with one value. For example, the definition of an error response states that "kind" must be "error" as follows:

components:
  responses:
    error:
      content:
        application/json:
          schema:
            properties:
              kind:
                type: string
                enum: [error]
              ... (more properties) ...

In the Swagger 3.x editor, the Model view of the response shows that property as:

Enum:
   > Array [ 1 ]

When opening the > twistie, the enumeration shows its one value:

Enum:
   v [ error ]

That is quite inconvenient, and a const definition for such a fixed value would allow the editor to show the value right away.

Plus, stating a required fixed value via a construct such as "const" is semantically really much more to the point of what the interface wants to express in such a case., compared to defining an enum with one value.

I'm looking forward to see OpenAPI 3.1 embrace this feature from the JSON schema.