Mark required and optional fields in definitions

[Richard-Degenne]

Objects such as listensForUser do not define any required properties.

I'm currently developing a Ruby wrapper for the API and it's not clear what fields are always present and which one are optional. Adding this information to the documentation would be a great tool to ensure a good symmetry with the API typings.

Example

      listens:
        type: array
        items:
          type: object
          required: # <= Here
            - inserted_at
            - listened_at
            - track_metadata
          properties:
            inserted_at:
              type: integer
            listened_at:
              type: integer
            recording_msid:
              type: string
            track_metadata:
              $ref: '../common/trackMetadata.yaml'
            user_name:
              type: string

[rain0r]

The example you provided is a response from the ListenBrainz api. It describes the data structure of the response when calling /1/user/(user_name)/listens.

So you won't have to create them yourself.

To call the api under /1/user/(user_name)/listens, you might take a look at paths/core/listensForUser.yaml.

There are all possible parameters described. If a parameter is required, it has required: true.

[Richard-Degenne]

Yes, I am aware. I am talking about the schema of the responses, not the parameters of the requests.

For instance, if I'm querying for listens, am I guaranteed that every single listen will always have a listened_at? A track_metadata? A track_metadata.mbid_mappings.artists.join_phrase?

This is called "Fixed keys" in OpenAPI's documentation.

If a dictionary has some fixed keys, you can define them explicitly as object properties and mark them as required.

-- https://swagger.io/docs/specification/v3_0/data-models/dictionaries/#fixed-keys

[rain0r]

Okay then. I'm sorry I didn't get what you meant.

The truth is, the API is, in my experience, a little fluid. Some fields may be removed, others added, some renamed.

Obviously not the "core" fields on the /1/user/(user_name)/listens endpoint (see JSON Documentation), but on other endpoints. I try my best to stay up to date.

The documentation provides a JSON sample for each API endpoint, but those snipptes are often incomplete. So what I did is going around, calling each endpoint and then build a yaml schema for each response.

Long story short: no, that's not guaranteed, unfortunately.

[Richard-Degenne]

Yeah, that's what I feared.

I guess I'll try something very defensive: start with all fields mandatory and scale back as I find optional ones. 😂

[rain0r]

Good luck for your project!

[RustyNova016]

Sorry to continue this after having it closed, but if we PR changes for fields that are known to be required/always returned, would it be accepted? I might contribute by giving marking some fields I know are certain

[rain0r]

Yes, if the schema can still be used to generate code that passes the tests, that would be fine.

Thanks!