Improve schema's metadata, namely titles and descriptions

[JBBianchi]

What would you like to be added:
I would like to add more titles and descriptions in the JSON Schema of the spec.

Why is this needed:
This metadata is useful for documentation and code generation.

For instance, in the current state (1.0.0-alpha2), schema is defined as:

schema:
  type: object
  properties:
    format:
      type: string
      default: json
      description: The schema's format. Defaults to 'json'. The (optional) version of the format can be set using `{format}:{version}`.
  oneOf:
    - properties:
        document:
          description: The schema's inline definition.
      required: [ document ]
    - properties:
        resource:
          $ref: '#/$defs/externalResource'
          description: The schema's external resource.
      required: [ resource ]
  description: Represents the definition of a schema.

Which, when generating TS types with json-schema-to-typescript, will result in:

export type Schema = {
  /**
   * The schema's format. Defaults to 'json'. The (optional) version of the format can be set using `{format}:{version}`.
   */
  format?: string;
  [k: string]: unknown;
} & (
  | {
      /**
       * The schema's inline definition.
       */
      document: {
        [k: string]: unknown;
      };
      [k: string]: unknown;
    }
  | {
      /**
       * The schema's external resource.
       */
      resource:
        | string
        | {
            /**
             * The endpoint's URI.
             */
            uri: string;
            /**
             * The authentication policy to use.
             */
            authentication?: AuthenticationPolicy | string;
            /**
             * The external resource's name, if any.
             */
            name?: string;
            [k: string]: unknown;
          };
      [k: string]: unknown;
    }
);

Which is accurate but not elegant.

If we provide more metadata, for instance:

schema:
  type: object
  properties:
    format:
      type: string
      default: json
      description: The schema's format. Defaults to 'json'. The (optional) version of the format can be set using `{format}:{version}`.
  oneOf:
    - properties:
        document:
          description: The schema's inline definition.
      required: [ document ]
      title: Document # <----------------------------
    - properties:
        resource:
          $ref: '#/$defs/externalResource'
          description: The schema's external resource.
      required: [ resource ]
      title: Resource # <----------------------------
  description: Represents the definition of a schema.

The generated code becomes more elegant:

/**
 * The schema used to describe and validate the input of the workflow or task.
 */
export type Schema = {
    /**
     * The schema's format. Defaults to 'json'. The (optional) version of the format can be set using `{format}:{version}`.
     */
    format?: string;
    [k: string]: unknown;
} & (Document | Resource);

export interface Document {
    /**
     * The schema's inline definition.
     */
    document: {
        [k: string]: unknown;
    };
    [k: string]: unknown;
}
//...

WDYT ?

[cdavernas]

@JBBianchi Great idea! In addition, afaik and aside from the required work, this has no impact other than improving the doc, so I say go ahead! 😀

[JBBianchi]

Closed by #968