$ref inheritance not supported

[JBBianchi]

When modeling inheritance, we can use $ref to point to an existing definition and extend it.

e.g.:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Sample",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "neighborhood": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/person"
      }
    }
  },
  "$defs": {
    "baseType": {
      "title": "BaseType",
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    },
    "person": {
      "title": "Person",
      "$ref": "#/$defs/baseType",
      "type": "object",
      "unevaluatedProperties": false,
      "properties": {
        "age": {
          "type": "number"
        }
      }
    }
  }
}

and the expected output to be equivalent to:

export interface Sample {
  neighborhood?: Person[];
}
export interface Person extends BaseType {
  age?: "number";
}
export interface BaseType {
  name?: string;
}

But with the provided code, the output of json-schema-to-typescript (14.1) with default options will be erroneous:

• There won't be any type generated for BaseType even if it's "reachable"
• Properties from BaseType will be missing in Person
• Person object can have extra properties even though unevaluatedProperties is set to false

Here is the generated output with the default settings:

export interface Sample {
  neighborhood?: Person[];
}
export interface Person {
  age?: "number";
  [k: string]: unknown;
}

Even by enabling unreachableDefinitions, the output isn't better. BaseType appears but it's still not used properly.

export interface Sample {
  neighborhood?: Person[];
}
export interface Person {
  age?: "number";
  [k: string]: unknown;
}
/**
 * This interface was referenced by `Sample`'s JSON-Schema
 * via the `definition` "baseType".
 */
export interface BaseType {
  name?: string;
  [k: string]: unknown;
}
/**
 * This interface was referenced by `Sample`'s JSON-Schema
 * via the `definition` "person".
 */
export interface Person1 {
  age?: "number";
  [k: string]: unknown;
}

The closest schema that would produce something close to the expected result would be:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Sample",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "neighborhood": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/person"
      }
    }
  },
  "$defs": {
    "baseType": {
      "title": "BaseType",
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    },
    "person": {
      "title": "Person",
      "type": "object",
      "allOf": [
        { "$ref": "#/$defs/baseType" },
        {
          "properties": {
            "age": {
              "type": "number"
            }
          },
          "unevaluatedProperties": false
        }
      ]
    }
  }
}

Edit: I removed a part I was talking about using additionalProperties to store the $ref but I was mistaken, it's not the same behavior.

[petrosv91]

Any update on that? I have the same issue.

[noootch]

+1 on this bug.

We are working with pydantic in our project and they recently removed their workaround for this bug so that now we have to rebuild this workaround as long as this bug is not solved.

Here is a comment that leads to the bugfix in the json schema.

Is it possible that this issue is due to the underlying ref parser? I found this discussion and it seems it won't be solved there. From my understanding to solve this bug the ref parser needs to be changed or a user setting has to be added that allows to switch the ref parser.

[bergamoticus]

Excuse me, how exactly should inheritance $ref be differentiated from reuse $ref
Is it that the first $ref is inheritance ref and the interface must be extended then?
Or is it all refs within allOf after "type": "object" ?

[JBBianchi]

Excuse me, how exactly should inheritance $ref be differentiated from reuse $ref Is it that the first $ref is inheritance ref and the interface must be extended then? Or is it all refs within allOf after "type": "object" ?

Do you have more context about inheritance vs reuse ? I must admit I don't understand you question(s). Some samples maybe and expected output ?

[bergamoticus]

Sorry for sending unclear message. I tried to illustrated it with the example below:

[bergamoticus]

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Function",
    "type": "object",
    "additionalProperties": false,
    "allOf": [
        {
            "$ref": "#/$defs/baseType"
        },
        {
            "properties": {
                "in": {
                    "$ref": "#/$defs/taggedValue"
                },
                "out": {
                    "$ref": "#/$defs/taggedValue"
                }
            }
        }
    ],
    "$defs": {
        "baseType": {
            "title": "BaseType",
            "type": "object",
            "properties": {
                "name": {
                    "type": "string"
                }
            }
        },
        "taggedValue": {
            "title": "TaggedValue",
            "type": "object",
            "properties": {
                "tag": {
                    "type": "string"
                },
                "value": {
                    "type": "number"
                }
            }
        }
    }
}

[bergamoticus]

Actual output:

export type Function = BaseType & {
  in?: TaggedValue;
  out?: TaggedValue;
  [k: string]: unknown;
};

export interface BaseType {
  name?: string;
  [k: string]: unknown;
}
export interface TaggedValue {
  tag?: string;
  value?: number;
  [k: string]: unknown;
}

[bergamoticus]

Desired output:

export interface Function extends BaseType  {
  in?: TaggedValue;
  out?: TaggedValue;
};

export interface BaseType {
  name?: string;
}
export interface TaggedValue {
  tag?: string;
  value?: number;
}

[bergamoticus]

In the above example $ref is intended to be used for
a) extending BaseType
b) shortcut/reuse TaggedValue for properties in and out. I think the correct term in UML is composition

My question is how to distinguish these different uses of ref? What is the criteria?

For instance, refs, under properties are for composition,
and refs used out of properties is for inheritance (and and interface must be extended)

[sgoll]

We have just been bitten by the same issue. In our case, we use schemars to derive JSON Schema from Rust definitions which we then convert to TypeScript with json-schema-to-typescript. For certain types of inputs (tagged enums), the JSON schema ends up similar to the one described in this issue, e.g.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "MyEnum",
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "const": "MyVariant"
        }
      },
      "$ref": "#/$defs/MyDefinition",
      "required": [
        "kind"
      ]
    }
  ],
  "$defs": {
    "MyDefinition": {
      "type": "object",
      "properties": {
        "my_attribute": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0
        }
      },
      "required": [
        "my_attribute"
      ]
    }
  }
}

Unfortunately, this generates the following incomplete TypeScript types:

export type MyEnum = MyDefinition;

export interface MyDefinition {
  kind: "MyVariant";
  [k: string]: unknown;
}

Due to the JSON Schema itself being generated, we cannot easily apply the workaround with allOf described above.

[sgoll]

After some further digging, the underlying problem seems to be that json-schema-ref-parser doesn't fill in the $ref in the given schemas.

I think the relevant fixes have been made in APIDevTools/json-schema-ref-parser#398 which was released in version 15.0.0. And indeed, when I manually upgrade to that version, the resulting TypeScript types look correct:

export type MyEnum = MyDefinition;

export interface MyDefinition {
  my_attribute?: number;
  kind: "MyVariant";
  [k: string]: unknown;
}

Unfortunately I was only able to get this running with a test build, because browserify doesn't work correctly with the newer versions of json-schema-ref-parser, failing with SyntaxError. So the upgrade is not trivial, but maybe somebody can help here.

---

Regarding the original example in this issue, the resulting types look like this:

export interface Sample {
  neighborhood?: Person[];
}
export interface Person {
  name?: string;
  age?: number;
  [k: string]: unknown;
}

So the inheritance is still not preserved—this would indeed be non-trivial, because json-schema-ref-parser already handles parsing and unnesting of $ref—, but at least the types that are generated are complete now.