Unable to have `$ref`, `allOf`, etc under `properties` in a schema.

[jlhawn]

I ran into an issue where an API spec for Kubernetes has a definition for a type named JSONSchemaProps. This is used for the custom resources feature of k8s - you can define your own API resources and you supply a JSON schema. This means that a JSON schema actually needs to be defined as a JSON schema. This includes the properties $ref, allOf and others.

Unfortunately, a definition like this one results in errors:

{
  "definitions": {
    "io.k8s.apiextensions-apiserver.pkg.apis.apiextensions.v1beta1.JSONSchemaProps": {
      "description": "JSONSchemaProps is a JSON-Schema following Specification Draft 4 (http://json-schema.org/).",
      "properties": {
        "$ref": {
          "type": "string"
        },
...

Saying that $ref is expected to be of type string. In this case though, I would expect that it's a perfectly legal value. $ref is actually the name of that property! It seems like swagger-ui is special-casing it when it shouldn't be.

A similar error occurs with the allOf or anyOf properties where it expects them to be an array.

If this is not considered a bug in swagger-ui, is there a way to escape $ref so that you can actually describe a property whose name is literally $ref?

[shockey]

Hi @jlhawn, this is working for me in the latest Swagger-UI:

I'm not seeing any errors (besides the incomplete spec ones), and the $ref property renders as I would expect.

This was, however, an issue in earlier versions... it was patched in Swagger-Client last month: swagger-api/swagger-js#1214

[jlhawn]

@shockey Sorry, I guess the errors only occur when you have a nested definition using a $ref. Try this JSON on editor.swagger.io to see what I mean:

{
  "swagger": "2.0",
  "info": {
   "title": "Kubernetes",
   "version": "v1.8.8"
  },
  "paths": {
    "/foo": {
      "get": {
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/CustomResourceValidation"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "JSONSchemaProps": {
      "description": "JSONSchemaProps is a JSON-Schema following Specification Draft 4 (http://json-schema.org/).",
      "properties": {
        "$ref": {"type": "string"}
      }
    },
    "CustomResourceValidation": {
      "description": "CustomResourceValidation is a list of validation methods for CustomResources.",
      "properties": {
        "openAPIV3Schema": {
          "$ref": "#/definitions/JSONSchemaProps"
        }
      }
    }
  }
}

[jlhawn]

[heldersepu]

I think the problem is on your "$ref": {"type": "string"} that looks weird...

All the refs I've seen are more like the other one:
"$ref": "#/definitions/JSONSchemaProps"

[shockey]

@heldersepu the case here is actually trying to create a schema parameter by the name of "$ref". Don't worry, the same line of thinking tripped me up too 😉

---

@jlhawn hmm, yeah, I do see it now. I think I know what's happening.

In Swagger-Client's $ref resolver (which Swagger-UI uses under the hood), we always treat $ref as a blessed property name unless the node's path matches a predefined list of paths where freely named keys are allowed:

https://github.com/swagger-api/swagger-js/blob/master/src/specmap/helpers.js#L1

https://github.com/swagger-api/swagger-js/blob/d615bf013f7c915e354c8906e3761789b077722b/src/specmap/lib/refs.js#L48-L50

Subschemas, clearly, are not included in this whitelist.. so this implementation will need to be reworked to support arbitrarily deep subschemas.

[heldersepu]

@shockey ye, this was a weird one!
I managed to reproduce it on my sample C# WebApi:
http://swashbuckletest.azurewebsites.net/swagger/ui/index
it shows the error but it passes validation

And I used allOf, I think this also is part of this:
https://github.com/swagger-api/swagger-js/blob/bdf670148a68bc40e9684a098baf5f060631a5f7/src/specmap/lib/all-of.js#L16

[heldersepu]

@shockey I was looking closely at the freelyNamedKeyParents and properties is not on the list.