support types refering to other types

[Khady]

Right now the deriver will create things such as

    "kind_f": { "$ref": "#/definitions/kind" },

But the definitions are not added to the final json schema

[Khady]

Some kind of manual support was added in 978987a

It isn't automatic. One can add some @ref attribute and then feed the list of descriptions to the function creating the full schema.

let print_schema ?definitions ?id ?title ?description s =
  let s = Ppx_deriving_jsonschema_runtime.json_schema ?definitions ?id ?title ?description s in
  let () = print_endline (Yojson.Basic.pretty_to_string s) in
  ()

type numbers = int list [@@deriving jsonschema]

type player_scores = {
  player : string;
  scores : numbers; [@ref "numbers"] [@key "scores_ref"]
}
[@@deriving jsonschema]

let () =
  print_schema ~id:"https://ahrefs.com/schemas/player_scores" ~title:"Player scores"
    ~description:"Object representing player scores"
    ~definitions:[ "numbers", numbers_jsonschema ]
    player_scores_jsonschema

Will generate a schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ahrefs.com/schemas/player_scores",
  "title": "Player scores",
  "description": "Object representing player scores",
  "$defs": { "numbers": { "type": "array", "items": { "type": "integer" } } },
  "type": "object",
  "properties": {
    "scores_ref": { "$ref": "#/defs/numbers" },
    "player": { "type": "string" }
  },
  "required": [ "scores_ref", "player" ]
}

We could have something more automatic, where all the fields of a record are automatically turned into references, and being able to pull the definitions for those types at runtime just before actually creating the json for the whole schema. But at this point it feels overkill. And the result would be quite brittle, as two types from different modules but with the same name could create some clashes inside the defs object.

Maybe without going that far it would be useful to change the definition a bit. So that we would generate a type like type jsonschema_type = { typ: [ `Assoc of _ ]; refs: (string * jsonschema_type) list }. With typ being what is generated for now. And with refs being populated for all the fields that have a @ref annotations.