Question: how to allow `oneOf` selection in Schema combinations

[SecretJuJu]

I am defining an API specification as follows:

export type MyController = Tspec.DefineApiSpec<{
  tags: ['ABC'];
  basePath: '/abc';
  paths: {
    '/': {
      post: {
        operationId: 'abc';
        summary: 'abc';
        responses: {
          201: Success;
          400:
            | ExceptionSpec<A>
            | ExceptionSpec<B>
            | ExceptionSpec<C>;
        };
      };
    };
  };
}>;

Currently, the schema automatically uses anyOf for combining the exception specifications (A, B, C) in the 400 response.

Issue

I want to use oneOf instead of anyOf, but I can't find a way.

Could you provide guidance on how to modify the schema definitions or adjust the library settings to use oneOf for the 400 response schemas?

Thank you for your help!

[hyeonss0417]

Thank you for your question!

The anyOf vs oneOf behavior comes from the underlying typescript-json-schema library, which converts TypeScript union types (A | B | C) to JSON Schema anyOf.

Current Limitation:
There's no built-in way to switch from anyOf to oneOf in tspec currently, as this is determined by the schema generation library.

Workaround Options:

1. Post-processing: You can post-process the generated OpenAPI spec to replace anyOf with oneOf where needed:

   const spec = await generateTspec({ ... });
   // Replace anyOf with oneOf in specific schemas
   const modifiedSpec = JSON.parse(
     JSON.stringify(spec).replace(/"anyOf"/g, '"oneOf"')
   );

2. Discriminated Unions: If your types have a discriminator property (like type), OpenAPI's discriminator keyword can help clients understand which schema applies:

   type ErrorA = { type: 'A'; messageA: string };
   type ErrorB = { type: 'B'; messageB: string };
   type ErrorC = { type: 'C'; messageC: string };
   
   // The union will use anyOf, but the discriminator helps
   type Error400 = ErrorA | ErrorB | ErrorC;

3. Feature Request: We could potentially add a @oneOf JSDoc annotation support in the future to allow explicit control over this behavior. Would this be helpful for your use case?

For most practical purposes, anyOf and oneOf behave similarly when the schemas are mutually exclusive (which is typically the case with discriminated unions). The main difference is validation strictness - oneOf requires exactly one schema to match, while anyOf requires at least one.

Let me know if you'd like us to prioritize adding explicit oneOf support!