Override the JsonPropertyDescription for $ref

[sureshms]

This project is awesome. This is the heart of open-source project we are building - OpenMetadata. Thank you 🙏.

In the following case where type.json has the following:

{
  "definitions": {
    "entityName": {
      "description": "Name that identifies an entity.",
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  }
}

This type is reused to defined entity names as shown below in person.json as follows:

{
  "properties": {
    "name": {
      "description": "Name of the person.",
      "$ref": "type.json#/definitions/entityName"
    }
  }
}

When code is generated for Person.java, the name field has JsonPropertyDescription that corresponds to the $ref Name that identifies an entity, instead of Name of the person. Is there any way to override the $ref description with the description where it is being referenced?

[joelittlejohn]

Great to hear about your project.

Right now ref replaces all other properties (the JSON schema spec used to mandate this behaviour). Now I think we should merge these properties with the referenced schema.

[sureshms]

@joelittlejohn, OpenMetadata community is a big fan of your work on this project. Look at the type system we have built for data analytics here and entities that are built using that type system here. JsoncSchema2Pojo is at the heart of our project 🎉 . All our java code is generated using it and that has given us a a lot of productivity avoiding writing boilerplate code. Keep up the amazing work.

Yes, to go from a more generic description in reused types to a more specific description where it is referenced would be a great feature.

[MonsieurBon]

@joelittlejohn at swiss post we are using this library as part of our project apikana-java via the jsonschema2pojo-maven-plugin. We are affected by this issue, because the generated javadoc description does not describe the property but the datatype. It also differs by how other libraries are handling it. We also use json-schema-to-typescript to generate typescript classes for our angular frontends and that library is handling it different by only considering the property description and not the referenced type.

Would you be open for a PR for this issue? How would you like it to be resolved? Should the descriptions of the property and the referenced type be merged?

[joelittlejohn]

@MonsieurBon great to hear about apikana-java!

Originally, the JSON schema spec dictated that when $ref is used, all other properties that appear alongside $ref MUST be ignored. This is because the references schema must replace the object containing the $ref entirely. The behaviour dictated by the spec has since changed though, and now the 'results' of the $ref should be considered to be the 'results' of the referenced schema. See 8.2.3.1. Direct References with "$ref".

I think this means that the correct behaviour is to merge ALL properties that sit alongside $ref into the result of the ref.

[MonsieurBon]

Yes, for description it is also explained under 7.7.1.1. Distinguishing Among Multiple Values with an example.