Improve output for top level $ref

[dherges]

A $ref breaks when used on the root object

Example A

Non-working example:

{
 "$schema": "http://json-schema.org/draft-04/schema#",
 "type": "object",
 "$ref": "#/definitions/anatomic-location",
  "definitions": {
    "anatomic-location": {
      "description": "thing",
      "properties": {
        /* .. */
        "children": {
          "type": "array",
          "items": { "$ref": "#/definitions/anatomic-location" }
        },
      }
    }
  }
}

Error message will be:

Refs should have been resolved by the resolver!

It will log:

  title: 'AnatomicLocation',
  properties: 
   { id: { type: 'integer' } },
  '$ref': '#' }

I wonder where the $ref: '#' comes from?

Example B

Working but with duplicated interface

  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "$ref": "#/definitions/anatomic-location/properties"
  },
  "definitions": {
    "anatomic-location": {
      "description": "thing...",
       "properties": { /* .. */ }
     }
  }
}

Generated code is:

export interface AnatomicLocation {
  id?: number;
  children?: AnatomicLocation1[];
}

export interface AnatomicLocation1 {
  id: number;
  children?: AnatomicLocation1[];
}

[bcherny]

Thanks for the reports @dherges.

@BigstickCarpet Is Example A kosher?

[bcherny]

@dherges Can you post the complete JSON-Schema for Example B? From what you gave it's not clear to me why the output is incorrect.

[dherges]

Hi @bcherny,

thanks for the response and your time! Here are the full repros.

Example A

{
  "title": "Example Schema",
  "definitions": {
    "person": {
      "type": "object",
      "properties": {
        "firstName": {
          "type": "string"
        },
        "children": {
          "type": "array",
          "items": { "$ref": "#/definitions/person" }
        }
      }
    }
  },
  "type": "object",
  "$ref": "#/definitions/person"
}

Error message:

$ node_modules/.bin/json2ts wound-ui/ui/foo.json 
error Refs should have been resolved by the resolver! { title: 'Example Schema',
  definitions: { person: { type: 'object', properties: [Object] } },
  type: 'object',
  required: [],
  additionalProperties: true,
  id: 'Foo',
  properties: 
   { firstName: { type: 'string' },
     children: { type: 'array', items: [Object] } },
  '$ref': '#' }

Example B

{
  "title": "Example Schema",
  "definitions": {
    "person": {
      "type": "object",
      "properties": {
        "firstName": {
          "type": "string"
        },
        "children": {
          "type": "array",
          "items": { "$ref": "#/definitions/person" }
        }
      }
    }
  },
  "type": "object",
  "properties": {
    "$ref": "#/definitions/person/properties"
  }
}

export interface ExampleSchema {
  firstName?: string;
  children?: Person[];
  [k: string]: any;
}
export interface Person {
  firstName?: string;
  children?: Person[];
  [k: string]: any;
}

I could live by that output as it's somewhat 'okay' due to duck typing in TypeScript world, but I wonder why two interfaces are being generated?!?

[dherges]

I found two working version by setting $ref: '.' and $ref: '#' in the properties.children.items:

{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string"
    },
    "children": {
      "type": "array",
      "items": { "$ref": "." }
   }
  }
}

export interface Bar {
  firstName?: string;
  children?: Bar[];
  [k: string]: any;
}

---

{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string"
    },
    "children": {
      "type": "array",
      "items": { "$ref": "#" }
   }
  }
}

export interface Bar {
  firstName?: string;
  children?: Bar[];
  [k: string]: any;
}

[JamesMessinger]

@bcherny - Example A in @dherges' post isn't supported by json-schema-ref-parser. It's technically not a valid JSON Schema, since a JSON Reference object is only allowed to have a $ref property (any other property are ignored, per the spec).

{
  "$ref": "#/foo/bar",
  "name": "Foo"               // <--- not allowed
}

That said, json-schema-ref-parser supports JSON Reference objects with additional properties, even though that's not technically spec-compliant. I chose to support it because many people asked for it and had real-world situations where they relied on it. However, allowing a non-spec-compliant feature causes problems such as the one that @dherges is facing.

My recommendation is to go with something like Example B in @dherges' post. Even though it may not seem quite as elegant, it is spec-compliant.

[bcherny]

@BigstickCarpet As always, thanks for chiming in.

@dherges You heard it here, Example A is invalid. For example B, nicer output might be:

export type ExampleSchema = Person
export interface Person {
  firstName?: string;
  children?: Person[];
  [k: string]: any;
}

Is that what you had in mind?

[bcherny]

@dherges Can you chime in?

[dherges]

Yes, exactly!