json schema property description and "$ref" usage

Question

I am writting a json schema to validate my json outputs produced by an exe.The schema being little bit complexe, I have defined some "definitions" that are referenced in properties ("$ref": "#/definitions/...). And using definitions here is all the more important because I have a case where the definition is recursive.

My schema now works well, it validates correctly my json outputs.

Now, I am trying to document the schema correctly using "description" keyword for each property. To develop the schema I use an editor (XMLSpy) that represents the schema graphically. It is very usefull but I face a curious behaviour and I do not know if it is a problem in the editor or if it is me that do not really understand.

Here is a minimal example of json schema to explain my problem:

{
 "$schema": "http://json-schema.org/draft-04/schema#",
 "type": "object",
 "properties": {
  "sourcePath": {
   "$ref": "#/definitions/Path",
   "description": "Here the description where I expected to set it"
  },
  "targetPath": {
   "$ref": "#/definitions/Path",
   "description": "Here another description where I expected to set it to that property of the same kind but whith a different use."
  }
 },
 "additionalProperties": false,
 "definitions": {
  "Path": {
   "description": "Here the descriptiond where it is set by the software",
   "type": "object",
   "properties": {
    "aUsefulProperty": {
     "type": "string"
    },
    "parentPath": {
     "$ref": "#/definitions/Path",
     "description": "Here yest another description where I expected to set it.."
    }
   },
   "required": [
    "aUsefulProperty"
   ],
   "additionalProperties": false
  }
 }
}

When I am trying to add a description to a property, the editor actually add a description inside the definition of the object. In consequence the editor displays this description for both properties "sourcePath" and "targetPath", moreover it displays this description also in "parentPath".

My intent is to have three different descriptions one for each property, (and probably also the definition itself but it is not the problem here). If I add them manually to the json schema, there is no problem but these descriptions does not appear in the graphical editor.

So, I am confused.

Do you think it is a problem with my graphical editor or am I wrong?

Basically, when we use a "$ref" to define a property, is it possible to add some other field as the description or does using a "$ref" imply not using nothing else? In that case, how can I document correctly a property?

I have to provide my json schemas to some partners, that will have to use them as documentation to produce correct json output. So, as far as possible, I would like to provide to them a self-documenting json schema as we can do with XML.

Thanks

Answer 1

Any members other than "$ref" in a JSON Reference object SHALL be ignored.

• https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03#section-3

In order to set a description, you would have to do something like the following example. It might cause other weirdness in you editor, but I'm pretty sure this is the cleanest way to do it.

Original:

{
    "$ref": "#/definitions/Path",
    "description": "Here the description where I expected to set it"
}

Suggested Correction:

{
    "allOf": [{ "$ref": "#/definitions/Path" }],
    "description": "Here the description where I expected to set it"
}

Answer 2

Overriding keywords from $refs is allowed under the current JSON Schema draft. The schema in the the original question would be considered valid (depending on the draft...)

From Original Post

    ...
    "properties": {
        "sourcePath": {
            "$ref": "#/definitions/Path",
            "description": "Here the description where I expected to set it"
        },
        "targetPath": {
            "$ref": "#/definitions/Path",
            "description": "Here another description where I expected to set it to that property of the same kind but whith a different use."
        }
    },
   ...

The JSON Schema spec includes an identical example:

From JSON Schema Draft2019

            ....
            "properties": {
                "enabled": {
                    "description": "If set to null, Feature B
                                    inherits the enabled
                                    value from Feature A",
                    "$ref": "#/$defs/enabledToggle"
                }
            }
            ...

The use-case in the question was exactly what the JSON Schema spec describes. In fact, you can override any of the annotation keywords (ie. title, description, default, examples). The example linked above also shows overriding the "default" property.

Unfortunately, the standard makes implementing this optional.

Applications MAY make decisions on which of multiple annotation values to use based on the schema location that contributed the value. This is intended to a allow flexible usage.

So you should test this before relying on it.