json schema property description and "$ref" usage

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"
}

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.