Description for property in schema is not respected

[marekott]

---

TLTR
It is impossible to set seperate descriptions for properties of the same type where one is described by $ref and also description for such propertie is not respected beside it is a valid case. You can find an example of such structure here: https://json-schema.org/learn/getting-started-step-by-step.html.

"warehouseLocation": {
  "description": "Coordinates of the warehouse where the product is located.",
  "$ref": "https://example.com/geographical-location.schema.json"
}

---

Hi @JamesNK,
after our last conversation about reading comments from code and puting them in description fields of schema I was working on such feature in my application. I was doing something like this:

var generator = new JSchemaGenerator
{
    SchemaIdGenerationHandling = SchemaIdGenerationHandling.None,
    SchemaLocationHandling = SchemaLocationHandling.Inline,
    SchemaReferenceHandling = SchemaReferenceHandling.Objects,
};
var schema = generator.Generate(typeof(User));

int i = 0;
foreach (var schemaProperty in schema.Properties)
{
    schemaProperty.Value.Description = $"{schemaProperty.Key}:{i++}";
}
Console.WriteLine(schema.ToString(SchemaVersion.Draft7));

public class User
{
    public int Age { get; set; }
    public Address Address1 { get; set; }
    public Address Address2 { get; set; }
}

public class Address
{
    public string Street { get; set; }
}

Expected result:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "Age": {
      "description": "Age:0",
      "type": "integer"
    },
    "Address1": {
      "description": "Address1:1",
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "Street": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "Street"
      ]
    },
    "Address2": {
      "$ref": "#/properties/Address1",
      "description": "Address2:2",
    }
  },
  "required": [
    "Age",
    "Address1",
    "Address2"
  ]
}

Actual result:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "Age": {
      "description": "Age:0",
      "type": "integer"
    },
    "Address1": {
      "description": "Address2:2",
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "Street": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "Street"
      ]
    },
    "Address2": {
      "$ref": "#/properties/Address1"
    }
  },
  "required": [
    "Age",
    "Address1",
    "Address2"
  ]
}

Altering description on Address2 is also overriding description for Address1. Whats more, int the end description for Address2 is not included. Is it expected bahaviour or bug? If is is expected how can I set seperate descriptions for both Addresses and also include the one that is correlated with property described by $ref?

[marekott]

Also, I tried to check how you handle it when properties are decorated with DescriptionAttribute (https://www.newtonsoft.com/jsonschema/help/html/GenerateWithDescriptions.htm). According to your documentation, in order to add descriptions I should do it as follow.

public class User
{
    public int Age { get; set; }
    [Description("This is Address1")]
    public Address Address1 { get; set; }
    [Description("This is Address2")]
    public Address Address2 { get; set; }
}

Expected result:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "Age": {
      "type": "integer"
    },
    "Address1": {
      "description": "This is Address1",
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "Street": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "Street"
      ]
    },
    "Address2": {
      "$ref": "#/properties/Address1",
      "description": "This is Address2",
    }
  },
  "required": [
    "Age",
    "Address1",
    "Address2"
  ]
}

Actual result:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "Age": {
      "type": "integer"
    },
    "Address1": {
      "description": "This is Address1",
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "Street": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "Street"
      ]
    },
    "Address2": {
      "description": "This is Address2",
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "Street": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "Street"
      ]
    }
  },
  "required": [
    "Age",
    "Address1",
    "Address2"
  ]
}

Why after using mentioned attribute SchemaReferenceHandling.Objects is not respected? Is it a bug or expected behaviour? It is a problem for me because based on schema (using external library) I am generating sample C# class for documentation purpose. When Address2 is not described by reference it is treated as seperate class and duplicate is generated.

[plachor]

Hi @JamesNK any comment on this topic? We would love to save schema with all objects referenced using ref but still we need to keep per property description as @marekott stated above. Current behavior looks like a bug.

[marekott]

Hi @JamesNK, any thoughts?

[DrG0rg]

Are there any updates?
I am having the issue myself.