[DISCUSSION] Flatten exported literal-union unions?

[alexchexes]

Hi!

At the moment, when an exported type is a union of other exported literal-only unions, the generator emits a separate definition for each constituent type and then references them from the parent union with anyOf. For example:

export type A = "foo" | "bar";
export type B = "baz" | "quz";

export type C = A | B;

export interface MyObject {
  foo: C;
}

Produces this schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "A": { "type": "string", "enum": ["foo", "bar"] },
    "B": { "type": "string", "enum": ["baz", "quz"] },
    "C": {
      "anyOf": [
        { "$ref": "#/definitions/A" },
        { "$ref": "#/definitions/B" }
      ]
    },
    "MyObject": {
      "type": "object",
      "required": ["foo"],
      "additionalProperties": false,
      "properties": {
        "foo": { "$ref": "#/definitions/C" }
      }
    }
  }
}

That output is perfectly valid, but in some situations it would be nicer if C were flattened into a single inline enum, because TypeScript ultimately resolves it to:

type C = "foo" | "bar" | "baz" | "quz";

This case isn't directly covered by the current test suite. My questions are:

1. Should we keep the existing behaviour and add a test to lock it in?
2. Or should we change the generator so that, when C is a union of exported literal enums, it merges the literals and inlines them, even though that duplicates the values already present in A and B?
3. Or should we add an opt-in flag like --flatten-union-literals that performs such flattening only when explicitly requested?

I'm happy to prepare a PR for either approach. What do you think?

[domoritz]

I think keeping the aliases is very valuable so I'd say option 1.

[arthurfiorette]

Keep the first behavior. I believe we already inline those if A, B and C are not exported.

[arthurfiorette]

I'm against adding more cli flags to the generator, but I believe some inline hints are a perfect fit for this scenario:

Imagine something like:

export type A = "foo" | "bar";
export type B = "baz" | "quz";

export type C = A | B;

export interface MyObject {
  /** @inline */
  foo: C;
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "A": { "type": "string", "enum": ["foo", "bar"] },
    "B": { "type": "string", "enum": ["baz", "quz"] },
    "C": {
      "anyOf": [
        { "$ref": "#/definitions/A" },
        { "$ref": "#/definitions/B" }
      ]
    },
    "MyObject": {
      "type": "object",
      "required": ["foo"],
      "additionalProperties": false,
      "properties": {
        "foo": { "type": "string", "enum": ["foo", "bar", "baz", "quz"] }
      }
    }
  }
}

[alexchexes]

I believe we already inline those if A, B and C are not exported

True, though I meant not inlining C into MyObject, but rather inlining A | B into C, so that the resulting schema in this example would look like:

"definitions": {
  // ...
  "C": { "type": "string", "enum": ["foo", "bar", "baz", "quz"] },
  "MyObject": {
    "type": "object",
    "required": ["foo"],
    "additionalProperties": false,
    "properties": { "foo": { "$ref": "#/definitions/C" } }
  }
}

But indeed, your idea about the @inline hint sounds good! I can draft a PR to add it.

We could also support:

export type A = "foo" | "bar";
export type B = "baz" | "quz";

/** @inline */ OR /** @flatten */
export type C = A | B;

which would emit:

"definitions": {
  "C": { "type": "string", "enum": ["foo", "bar", "baz", "quz"] }
}

or:

"definitions": {
  "A": { "type": "string", "enum": ["foo", "bar"] },
  "B": { "type": "string", "enum": ["baz", "quz"] },
  "C": { "type": "string", "enum": ["foo", "bar", "baz", "quz"] }
}

Let me know how you see this.

[arthurfiorette]

Omitting definitions of A and B ihmo is not an option.

@domoritz A /** @inline */ jsdoc annotaion is also awesome for tools that reads json schemas but does not supports references. I think we should indeed have this feature.

[domoritz]

I think it's a trade off. Sometimes people generate schemas for code they do not control so relying on annotations for features of the schema may not be the right thing. At the same time, I feel strongly against having more command line options as it increases the burden on maintenance.

Having said that, @inline seems like a useful annotation to be able to export a type but still hide it. Iirc we have a @hidden annotation as well which completely hides types.

[domoritz]

I implemented @hidden five years ago #329

[alexchexes]

@domoritz @arthurfiorette

Okay, before I start working on this, I need to clarify:

1. Do we now want to add @inline tag support that will make the generator behave exactly as @arthurfiorette showed in this example, right?

---

2. What should happen if the @inline tag is found in this context:

export type A = "foo" | "bar";
export type B = "baz" | "quz";

/** @inline */
export type C = A | B;

export interface MyObject {
  foo: C;
}

Do we just ignore it, or treat it as a hint that C must be inlined everywhere it is used, like in this other example:

export type A = "foo" | "bar";
export type B = "baz" | "quz";

/** @inline */
export type C = A | B;

export interface MyObject {
  foo: C;
}

export interface MyOtherObject {
  foo: C;
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "A": { "type": "string", "enum": ["foo", "bar"] },
    "B": { "type": "string", "enum": ["baz", "quz"] },
    "C": {
      "anyOf": [
        { "$ref": "#/definitions/A" },
        { "$ref": "#/definitions/B" }
      ]
    },
    "MyObject": {
      "type": "object",
      "required": ["foo"],
      "additionalProperties": false,
      "properties": {
        "foo": { "type": "string", "enum": ["foo", "bar", "baz", "quz"] }
      }
    },
    "MyOtherObject": {
      "type": "object",
      "required": ["foo"],
      "additionalProperties": false,
      "properties": {
        "foo": { "type": "string", "enum": ["foo", "bar", "baz", "quz"] }
      }
    }
  }
}

Or, if having this feature is desired but having dual-use for one tag is not, then we could probably add support for another tag, something like @inline-self. What do you think?

---

3. Given that in some cases we'd like to resolve or "flatten" the type to be represented in schema exactly as TypeScript sees it, like here:

export type A = "foo" | "bar";
export type B = "baz" | "quz";

/** @... */
export type C = A | B;

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "A": { "type": "string", "enum": ["foo", "bar"] },
    "B": { "type": "string", "enum": ["baz", "quz"] },
    "C": { "type": "string", "enum": ["foo", "bar", "baz", "quz"] }
  }
}

Should we consider adding any other tag or reuse the proposed @inline (or @inline-self) tags mentioned above to make this possible?

[arthurfiorette]

My votes:

1. Yes.
2. Export type A, B, C and MyObject, but type C is foo | bar | baz | quaz instead of a union of references of A and B. MyObject still references C.
3. Not for now, lets first try to merge this and only later, if needed, create a new PR for those other behaviors.

[alexchexes]

• Export type A, B, C and MyObject, but type C is foo | bar | baz | quaz instead of a union of references of A and B. MyObject still references C.

You mean from this code:

export type A = "foo" | "bar";
export type B = "baz" | "quz";

/** @inline */
export type C = A | B;

export interface MyObject {
  foo: C;
}

the generated schema should be:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "A": { "type": "string", "enum": ["foo", "bar"] },
    "B": { "type": "string", "enum": ["baz", "quz"] },
    "C": { "type": "string", "enum": ["foo", "bar", "baz", "quz"] },
    "MyObject": {
      "type": "object",
      "required": ["foo"],
      "additionalProperties": false,
      "properties": { "foo": { "$ref": "#/definitions/C" } }
    }
  }
}

?

If yes, then it automatically closes question # 3, but I'm not sure how we should formalize the logic of @inline usage then... need to think about this a bit more. Or do you already have a clearer picture?

[arthurfiorette]

Yes. Ideally @inline would just dereference everything by that type. Meaning that inner references are dereferenced and references for that type elsewhere would remain unchanged.