$ref pointers with escaped characters in strict structured output

API Bugs
1

Trying to reference a definitions (in $defs) that has a slash or tilde in it’s property name does not work. Here you would usually escape the slash in the JSON pointer of the $ref with a ‘~1‘, but the API then returns an error stating that the schema is invalid.

Instead, not escaping anything in the pointer works, but this may lead to a conflict. For example, suppose we’re using the following (hypothetical) schema:

{
  "type" : "object",
  "additionalProperties" : false,
  "properties" : {
    "A/properties/B" : {
      "$ref" : "#/$defs/A/properties/B"
    }
  },
  "required" : [ "A/properties/B" ],
  "$defs" : {
    "A/properties/B" : {
      "type" : "number"
    },
    "A" : {
      "type" : "object",
      "additionalProperties" : false,
      "properties": {
        "B" : {
          "type": "string"
        }
      },
      "required" : [ "B" ]
    }
  }
}

Possible outcomes from this are:

  • {"A/properties/B":""}
  • {"A/properties/B":0}
2

The problem happens because $ref pointers can’t handle / or ~ properly — even if you escape them.
Best and simplest solution: don’t use these characters in your $defs names.
Use normal names (like A_properties_B) instead of A/properties/B.
That way, your $ref will work without errors.