CODEWITHSUNDEEP
jsonschemajson-schema-validatorfastify
Pradip
Pradip

Reputation: 649

Open API schema conditional response field based on the presence of a query parameter

I am working on providing a GET REST API where I would like to conditionally include the total_documents field (its an integer count of the total number of records present in the DB table).

The API signature and response payload will be something like:

    GET /endpoint/?total_documents&.....

    Response Payload:
    {
         documents: [....],
         total_documents: 100
    }

Now I would like the total_documents field to be appeared in the response payload if and only if the total_documents query parameter exists in the URL.

This is what I tried, based on my schema:

 fastify.addSchema({
        $id: 'persistence-query-params',
        title: "PersistenceQueryParams",
        type: 'object',
        description: 'Persistence Service GET API URL query specification. Applicable for GET API only.',
        properties: {
            'total_documents': {
                description: 'Total number of documents present in the collection, after applying filters, if any. This query paramater does not take any value, just pass it as the name (e.g. &total_documents).',
                nullable: true,
            },
        },       
}

querystring: {
                description: 'Persistence Service GET API URL query specification. Applicable for GET API only.',
                $ref: 'persistence-query-params#',
            },
            response: {
                200: {
                    properties: {
                        'documents': {
                            description: 'All the retrieved document(s) from the specified collection for the specified service database and account.',
                            type: 'array',
                            items: {
                                $ref: 'persistence-response-doc#',                  
                            }
                        },
                        'total_documents': {
                            description: "If total_documents query paremeter is specified, gives the total number of documents present in the collection, after applying query paramaters, if any. If total_documents is not specified, this field will not be available in the response payload.",
                            type: 'number',
                            default: -1,
                        },
                    },
                    dependencies: {
                      'total_documents': { required: ['querystring/properties/total_documents'] },
                    },
                },
                '4xx': {
                    $ref: 'error-response#',
                    description: 'Error response.'
                }
            }

What is the way out here?

Thanks, Pradip

Upvotes: 0

Views: 2126

Answers (1)

Relequestual
Relequestual

Reputation: 12355

JSON Schema has no notion of a request or response or HTTP.

What you have here is an OpenAPI specification document.

The OpenAPI specification defines a way to access dynamic values, but only within Link Objects or Callback Objects, which includes the query params.

Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call. This mechanism is used by Link Objects and Callback Objects.

https://spec.openapis.org/oas/v3.1.0#runtime-expressions

JSON Schem has no way to reference instance data, let alone data relating to contexts it is unaware of.

Upvotes: 1

Related Questions