Different schema for different request content-type

[shadone]

This library seems amazing, I already use it for a small API service and quite happy with the design decisions behind express-sod-api <3

Now that I am starting to implement additional more complex APIs I am hitting a few issues I do not know how to resolve. Is it possible to have separate schemas depending on the content-type of the request?

Basically I want to implement an API that allow to POST either a JSON data or a file. Here is the OpenAPI that describes what I am trying to do:

paths:
  /foobar:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FoobarFromJSONRequest"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/FoobarFromDataRequest"

...

components:
  schemas:
    FoobarFromJSONRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string

    FoobarFromDataRequest:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          format: binary
          contentMediaType: application/octet-stream
        some_additional_field:
          type: string

[RobinTail]

well, it's not possible, @shadone
And frankly I'm not sure it should be. I'd advocate for single purpose routes.
From what I see, you want that endpoint either to process the given file or to take that file from a given url.
But you also want different response for those cases.
In this regard, I suggest you to make 2 routes for those requests (not to combine them), but to extract the actual data processing to a function that you could call from the handlers of both endpoints.
In the end, each would have its own input and output schema, but you won't repeat yourself in common parts.

[shadone]

Thanks for your reply and suggestions :) I have a different view in this particular case - for my API I felt it was appropriate to allow the same endpoint to accept either a file (as multipart/form-data) or a url (as application/json) payload. In my situation the response type is identical for both variants. This is a “submit job”-style API, where we take a job to either process an uploaded file or fetch and process a file from the provided URL, and then return a job identifier to the caller.

Although I could redesign the API to have separate endpoints for these cases, I had to give up on using express-zod-api for this part of the API due to time constraints. Because of this and a few other issues I encountered, I was struggling to get express-zod-api to generate the same (or even similar) OpenAPI spec to the one I had previously written by hand.

To elaborate: I already had a hand-written API spec, and I’m now trying to implement it using express-zod-api, with the goal of generating the OpenAPI spec directly from the implementation. As far as I can see, there are a few missing features for my use case:

• I had trouble with ez.dateOut() — I couldn’t get it to produce Date objects in the schema. The example from the README doesn’t seem to work for me, or maybe I’ve misconfigured something.
• There doesn't seem to be support for callbacks/webhooks, externalDocs for paths, named examples

I need to get the implementation working now, so I’m putting this aside for the moment, but I plan to revisit it and try to make express-zod-api work for me in a few weeks.

[RobinTail]

@shadone , Express Zod API supports different schema for different content type of ResultHandler response:

new ResultHandler({
  positive: (output) => [
    { schema: one, mimeType: "" },
    { schema: another, mimeType: "" },
  ],
});

But the content type of the Endpoint request is singular and depends on its input schema.
It's JSON by default, but the presence of ez.upload(), ez.raw() or ez.form() change it to multipart/form-data, application/octet-stream and application/x-www-form-urlencoded accordingly, including the parser used for handling the request body addressed to that Endpoint.

express-zod-api/express-zod-api/src/endpoint.ts

Lines 158 to 166 in e5da940

	public override get requestType() {
	const found = findRequestTypeDefiningSchema(this.#def.inputSchema);
	if (found) {
	const brand = getBrand(found);
	if (brand === ezUploadBrand) return "upload";
	if (brand === ezRawBrand) return "raw";
	if (brand === ezFormBrand) return "form";
	}
	return "json";

So, at the moment, it's not possible to accept different content types when requesting the same Endpoint.
It can, however, be the same URL requested with a different HTTP method, assigned with Endpoints having different input schemas.

[RobinTail]

@shadone ,

ez.dateOut() — I couldn’t get it to produce Date objects

dateOut makes type: "string" with format: "date-time". It's not Date object in the response, because JSON can't transport instances of classes, only plain things.

express-zod-api/express-zod-api/src/documentation-helpers.ts

Lines 164 to 178 in 38b9547

	export const depictDateOut: Depicter = (
	{ jsonSchema: { examples, description } },
	ctx,
	) => {
	if (!ctx.isResponse)
	throw new DocumentationError("Please use ez.dateIn() for input.", ctx);
	const jsonSchema: z.core.JSONSchema.StringSchema = {
	description: description || "YYYY-MM-DDTHH:mm:ss.sssZ",
	type: "string",
	format: "date-time",
	externalDocs: { url: isoDateDocumentationUrl },
	};
	if (examples?.length) jsonSchema.examples = examples;
	return jsonSchema;
	};

If it does not suit your needs, you can make your own branded schema with a custom depicter:

https://ez.robintail.cz/v25.6.0/customizable-brands-handling

[shadone]

Right, sorry I wasn't explained my issue correctly.

ez.dateOut() — I couldn’t get it to produce Date objects

I am following this documentation https://github.com/RobinTail/express-zod-api/?tab=readme-ov-file#dealing-with-dates

What I see is that it works if I copy the code verbatim, but if I use z.infer to get the Output type, that type has the createdAt field as a branded string, not Date type.

const OutputSchema = z.object({
  createdAt: ez.dateOut(),
});

type OutputType = z.infer<typeof OutputSchema>; // <<<--- z.infer is not aware of ez.dateOut, well obviously

const updateUserEndpoint = defaultEndpointsFactory.build({
  method: "post",
  input: z.object({
    userId: z.string(),
    birthday: ez.dateIn({ examples: ["1963-04-21"] }), // string -> Date in handler
  }),
  output: OutputSchema,
  handler: async ({ input }) => ({              // <<<--- This works
    createdAt: new Date("2022-01-22"), // 2022-01-22T00:00:00.000Z
  }),

  handler: async ({ input }): Promise<OutputType> => ({           // <<<--- This doesn't work
    createdAt: new Date("2022-01-22"), // 2022-01-22T00:00:00.000Z
  }),

});

This was unexpected and makes not possible to create a variable of the Output type e.g.

  handler: async ({ input }): Promise<OutputType> => ({           // <<<--- This doesn't work
    let result: OutputType | undefined;
    result = fetchResultFromSomewhere();
    return result;
  }),

[RobinTail]

but if I use z.infer

Don't use it, @shadone
z.infer<> is an alias for z.output<>, which for ez.dateOut(), being a transforming schema, is indeed a string.
The return type of the handler should be z.input<typeof OutputSchema>, because this is where you return Date which is later and internally transformed to that string.