No-$ref-siblings and "description"

I’m validation my OpenApi definition using Spectral. Everything is fine … just I don’t know how to solve an issue that I’ve with $ref and description

In my definition I’ve many models that have a “price” property that is a model too. So I’ve something like

"CartItem": {
"properties": {
    "total_price": {
        "description": "Total price for ...",
        "$ref": "#/components/schemas/Price"
    "total_price_with_vat": {
        "description": "Total price with vat"
        "$ref": "#/components/schemas/Price"

The point is that when I try to validate this I get “$ref cannot be placed next to any other properties” because “total_price” has “description” too …

I understand why $ref cannot be place next to other properties but how/where I describe the different prices ?



I think you got help with this on Slack, but… yep this is correct! Cant have stuff next to $ref in OAS3.0, but you’ll be allowed to in OAS3.1.

1 Like