Is there a best practice in apiary blueprint to specify field length (size) / format?

Question

If using MSON, the only way I see to currently include field length would be to include as part of the description. Are there any plans to add support for this or are there any best practices (workarounds) being used for this purpose?

as an example, in the below MSON description, how could I specify that the tokenType max length is say 20 chars? (contrived example)

## accessToken
+ tokenType: `Bearer` (string) - The type of access token that was issued.  Currently only 'Bearer' tokens are supported.
+ expiresIn: `1000` (number) - How much time in seconds until the token  expires.
+ accessToken: `0.AQAAAVF-mqsiAAAAAAAbd0A71bIG8IUwcgHV7mAYiG7J.EAAQsWDnpqRj7WwyFVLTsdo0yXWh9L4` (string) - The access token to pass in the API call to access the protected resource.

Answer 1

MSON doesn't support specifying validation options such as a maximum length at the moment. The API Blueprint team have been exploring adding these features but this is still open for discussion on the best way to support this. There could be lots of validations so it's definitely a large topic to cover so we will need to find a clear way to express validations, which offers future support for declaring so this can evolve.

There is an open discussion on https://github.com/apiaryio/mson/issues/43 on the topic. If you have any ideas or syntax proposals they would be greatly appreciated.

Currently, you can provide a custom JSON Schema which specifies your validation options. As an example, you can achieve this validation using the following API Blueprint:

+ Response 200 (application/json)
    + Attributes
        + tokenType: Bearer (fixed) - The type of access token that was issued.
        + expiresIn: 1000 (number) - How much time in seconds until the token expires.
        + accessToken: `0.AQAAAVF-mqsiAAAAAAAbd0A71bIG8IUwcgHV7mAYiG7J.EAAQsWDnpqRj7WwyFVLTsdo0yXWh9L4` (string) - The access token to pass in the API call to access the protected resource.

    + Schema

        {
          "$schema": "http://json-schema.org/draft-04/schema#",
          "type": "object",
          "properties": {
            "tokenType": {
              "type": "string",
              "enum": [
                "Bearer"
              ]
            },
            "expiresIn": {
              "type": "number"
            },
            "accessToken": {
              "type": "string",
              "maxLength": 20
            }
          },
          "required": [
            "tokenType"
          ]
        }

I agree, this solution isn't great since you will need to duplicate some information in your MSON attributes and the schema itself. It would be far more idea to be able to specify the validation directly in MSON.

Just wanted to mention, you can use fixed for tokenType to indicate it has a fixed value which does not change. You could also used enum in the future to allow for multiple tokenType options.