feat: Generate titles from definition names

[FoxxMD]

All root child definitions have a title added to their definition if the opt-in definitionTitles option is set

• The title value is the same as the node name (which is, ideally, the name of the interface/type/alias from TS code).
• Use definitionTitles: true programatically or from the command line with arg --definition-titles

Closes #1486

[arthurfiorette]

I'm not sure if this is the best place. Something inside getDefinition should be better. This doesn't work for deep objects/definitions, either.

[arthurfiorette]

@domoritz general idea seems fair, but I'm not sure if this is something we want to add (at least not just as an if statement in the SchemaGenerator.ts and not somewhere else)

[domoritz]

What's the reason for having titles? I don't like having extra CLI actions when possible.

[FoxxMD]

The reason for generating titles is that they are a valid property type for draft-07 json-schema and are used by some applications for displaying the names of definitions.

I use json-schema-plugin for Docusaurus to display my application's config to users in the documentation.

Without title properties on definitions the rendered schema is not user friendly.

With title properties on definitions the rendered objects have user-friendly names and the layout of the schema is simplified as well.

This is just the relevant example to me but I'm sure I'm not the only one who would benefit from having titles, since its a valid piece of the schema to consume.

---

I would have also preferred to avoid adding CLI args by instead using custom formatting for a definition but I could not find a way to get access to the node's name (CircularReferenceTypeFormatter) in a way that did not require refactoring.

In the last stage of appendRootChildDefinitions when reducing children definitions the final, rendered object comes from an ObjectType child of the parent CircularReferenceType which does not provide the derived name to this function.

If anyone has guidance on how I could better achieve this using a custom formatter I'd be happy to adapt this PR to do that instead but I was struggling for a simple way to get this result.

[arthurfiorette]

Seems valid to me, @domoritz your thoughts?

@FoxxMD please fix the formatting in the readme file as my above review.

[domoritz]

I think we should make titles the default but also

1. Make sure we url encode keys (which iirc is required by the spec) and use the non url encoded name as the title
2. Use the correct title as much as possible. So if there are duplicate names for example, the key may need a prefix to be unambiguous but the title may be ambiguous.

Does that seem reasonable?

[arthurfiorette]

Titles could be the default but should be available under a configuration option as well, otherwise this release would invalidate all previous generated schemas.

Maybe non-default until next major?

[domoritz]

Adding titles isn't a breaking change imo but should be a minor version bump. But I don't feel strongly about it.

[arthurfiorette]

It might not be a breaking change like builds failing, but this will increase the final JSON output by a considerable percentage since names will now be duplicated. Also, any kind of cache keys (hashed ones) will hash into different values even for the same input since a new field was added for every single schema present.

[FoxxMD]

Any thoughts regarding refactoring so this could be a custom formatter instead? I'll admit I don't fully grok the whole schema generation lifecycle but from what I observed while debugging:

Changing getDefinition signature in formatter

Adding a second name arg would solve this issue, with all applicable formatters returning their ObjectType child with the name passed. However, this doesn't support any users currently using a custom formatter (and potentially breaks them unless second arg is optional).

BaseType getName ?

This could be used but I don't fully understand why some types get a guid and some get the name of actual data structure used in TS. I might not be understanding this correctly though. If there was a way to set the data structure's name here, alongside the guid, then it could be used.

[domoritz]

Any thoughts regarding refactoring so this could be a custom formatter instead?

Yeah, I think this should/could be implemented as a formatter similar to the annotation formatter. We can already get the title via a comment so we should also make sure that we are letting people override the title with a comment.

[FoxxMD]

We can already get the title via a comment

can you elaborate on this a bit more? Where, in code?

[domoritz]

I don't have the exact syntax handy but with @title or @tjs-title you can set properties that will appear in the schema.