Square brackets in parameter name

Question

I was wondering if it's possible to include square brackets in the parameter name, which is how Rails groups parameters. For example:

    + Parameters
        + person[age] (string) ... Person's age

Right now if I include the square bracket, the parameter doesn't get rendered.

Thanks!

Answer 1

Technically square brackets are not allowed in an URI except the Internet Protocol Literal Address

RFC3513:

A host identified by an Internet Protocol literal address, version 6 [RFC3513] or later, is distinguished by enclosing the IP literal within square brackets ("[" and "]"). This is the only place where square bracket characters are allowed in the URI syntax.

Which implies the square bracket SHOULD NOT be used (unescaped) in a parameter name.

A solution for now would be to escape the brackets manually.

In the future the API Blueprint may automatically escape unsafe characters for you. Refer to:

• Report square brackets in URI templates
• Escape Unsafe Characters in URI Templates