How to model an optional response field?

[Mario Valle]

I have one of my endpoint returns a paginated list of documents.

Each page of results contains URL for next/prev/first/last page of output besides the array of documents to display.

If one of these actions make no sense, the corresponding field is missing.

For example the first query returns N entries plus the 'next' field for the next N documents and 'last' that display the last page of documents.

In the client it is easy to enable/disable navigation buttons based on the presence/absence of the corresponding URL in the server response.

But Swagger editor complains that 'A deterministic version of a JSON Schema object.' if I define the response this way:

prev:
  type: integer
  required: false

I think the alternative solutions, like returning an empty field if the action is not valid, are not so clear and changing the design just to satisfy the editor is questionable in my opinion.

Please enlighten me.

Thanks!

mario

[tony tam]

I think you're describing an optional property in a response schema.  In that case, the absence of being in the `required` array means it is optional:

Tag:
  required:
    - id
  properties:
    id:
      type: "integer"
      format: "int64"
    name:
      type: "string"

In this example `name` is optional while `id` is required.

[Mario Valle]

Thanks a lot!
Now it is clean and well documented.
Maybe I will open a ticket about a rewrite of http://swagger.io/specification/#schemaObject to make it clearer. I missed indeed the 'required' field.
Thanks again
                mario

Here is the entry in the definitions section:

 DocumentList:
     type: object
     required:
       - total
       - offset
       - count
       - ...
     properties:
       total:
         type: integer
         description: The total number of documents
       offset:
         type: integer
         description: The offset of this query
       count:
         type: integer
         description: The count of documents to be retrieved
     ...
       prev:
         type: integer
         description: The URL to access the previous page (not present if no previous page)
       first:
         type: integer
         description: The URL to access the first page (not present if already on the first page)
       next:
         type: integer
         description: The URL to access the next page (not present if no next page)
       last:
         type: integer
         description: The URL to access the last page (not present if already on the last page)