Swagger yaml - $ref values must be RFC3986-compliant percent-encoded URIs - swagger

Question

I got the following YAML, when I try this, in https://editor.swagger.io/ I'm getting "$ref values must be RFC3986-compliant percent-encoded URIs" error when I use [ and ] brackets, I tried encoding them but the response schema is not getting recognized, saying the reference is missing. Any help on what can be the issue in this scenario?
swagger: "2.0"
info:
title: test
version: "1.0"
paths:
/api/TestCustomer:
post:
consumes:
- application/json
- text/json
produces:
- application/json
- text/json
parameters:
- name: request
in: body
required: true
schema:
$ref: '#/definitions/UpdateTestCustomerRequest'
responses:
'201':
description: Test Response
schema:
$ref: '#/definitions/Result[UpdateTestCustomerResponse]' ***This line results in a error "$ref values must be RFC3986-compliant percent-encoded URIs"
definitions:
UpdateTestCustomerRequest:
type: object
properties:
CustomerId:
type: string
UpdatedBy:
type: string
Result[UpdateTestCustomerResponse]:
type: object
properties:
Status:
format: int32
enum:
- 201
type: integer
Response:
$ref: '#/definitions/UpdateTestCustomerResponse'
UpdateTestCustomerResponse:
type: object
properties:
CustomerId:
type: string

Answer 1

In OpenAPI 2.0, if some schema names contain special characters, they must be URL-encoded in the $ref paths. Replace [ with %5B and ] with %5D in the $ref path, e.g.:
# Incorrect
$ref: '#/definitions/Result[UpdateTestCustomerResponse]'
# Correct
$ref: '#/definitions/Result%5BUpdateTestCustomerResponse%5D'
Or better yet, don't use special characters in schema names.
If/when you migrate to OpenAPI 3, you'll have to remove the [ ] characters from schema names because the newer versions only allow A..Z a..z 0..9 _ . - in schema names.