How can I generate a schema with format: int32?

[KoharaKazuya]

I am trying to define an OpenAPI Document schema using Typia. Specifically, I am attempting to replicate the GeneralError example from the OpenAPI Specification v3.1.1.

https://github.com/OAI/OpenAPI-Specification/blob/ba75c2949fc475367d80a1178fd9a71a299e2375/versions/3.1.1.md#L609-L620

When I tested this on the Typia Playground, the output did not include format: "int32".

https://typia.io/playground/?script=JYWwDg9gTgLgBDAnmYBDANHA3g1BzAZzgF84AzKCEOAIiRVRoG4AoF4AOxgFMozUAxtzgBxbh16oANgFEolKNhZw4AiABNuAfgBccDgFcQAI15wAZLkIA6ACrJuAHhqcYAZgBMNAHysVIbgICfG09AhgoTjxWYjY1DnC4AgEAC24QVCIAXgRkNGsAKwIIDmtktIyCRwBtMQkoaTkFAF1vAAoASlYgA

How should I write the schema to output format: "int32"?

[samchon]

Is the format int32 supported only in the OpenAPI 3.1?

How about in the Swagger v2 or OpenAPI v3.0?

I will update both @samchon/openapi and typia after checking it.

[KoharaKazuya]

@samchon
I found that int32, int64, float, double, and password are included in Swagger v2, OpenAPI v3.0, and OpenAPI v3.1.
On the other hand, byte, binary, date, and date-time are only included in Swagger v2 and OpenAPI v3.0, but not in OpenAPI v3.1.

Here are the relevant references:

• Swagger v2
• OpenAPI v3.0
• OpenAPI v3.1

I hope this helps clarify things.

[samchon]

Looking at the Swagger v2 specification, both integer and number types can assign the format property like below.

However, looking at the OpenAPI v3 and OpenAPI v3.1 specs, the format seems like to be allowed only in the number type. To see the detailed specification of it, I've read the JSON schema specification document, but could not found the numeric types' format restriction.

Type	Formats
integer	int32, int64
number	int32, int64, float, double

Instead, I'd traveled another JSON schema based validator libraries like ajv and typebox, but both of them are not supporting the numeric types' format property either. The only one thing I could find was an ajv plugin library ajv-openapi, but it is not working on the latest ajv version.

When I've tested in the Swagger-UI, the numeric format restriction has not affected anything. The Swagger-UI just handled the numeric format restriction as unknown property.

Therefore, I should be careful about this suggestion. As it is not a regular specification of JSON schema, and even not well documented in the OpenAPI specification, we need more researches. Additionally, I'm wonder whethering that uint32 and uint64 formats should be allowed or not.

@sinclairzx81 do you have any idea about it? I wonder if you plan to support range restrictions such as int32 or float in 솓 typebox.

[samchon]

@KoharaKazuya If you still need the numeric format restriction right now, please use the JsonSchemaPlugin type instead for a while.

import typia, { tags } from "typia";

interface IMember {
  id: number & tags.JsonSchemaPlugin<{
    format: "float"
  }>;
}
typia.llm.parameters<IMember, "claude">();

https://typia.io/playground/?script=JYWwDg9gTgLgBDAnmYBDANHA3g1BzAZzgF84AzKCEOAIiRVRoG4AoF4AOxgFMozUAxtzgBJALLcQAI17YWcOMAAmALjgcArtNkAyXIQB0AKQIQOAZQEALSagAKAGw15OAHizyF5aCFQw1NGQOEH40nsQAfKzELPRoBg4OIAZgqFCoINw8UASu4pIyUJg0Ag6oGkrcNBEAFACUTEA

[samchon]

I will publish @samchon/openapi today, and decide whether to adjust to the typia after listening opinions.

[KoharaKazuya]

Wow, this is amazing. Thank you for sharing the workaround! It looks like this will resolve my issue for now.

I'm glad to see this resolved since I wanted to use it in combination with a documentation tool like ReDoc.
https://redocly.github.io/redoc/#tag/Events/operation/CreateSpecialEvent

---

FYI: In the OpenAPI Specification, starting from v3.0.4, there's a note that number and integer are essentially the same as JSON Data Types.
https://github.com/OAI/OpenAPI-Specification/blob/ba75c2949fc475367d80a1178fd9a71a299e2375/versions/3.0.4.md?plain=1#L187

In other words, in the OpenAPI Specification, a format definition for number also applies to integer.
I believe my understanding is correct, but please feel free to correct me if I’m mistaken.

That said, type: integer with format: int32 is clearly invalid, so it seems this needs careful consideration.
I hope this helps!

[samchon]

If { type: "integer", format: "int32" } is invalid, no way to support from library level.

You should keep using the JsonSchemaPlugin type.

When you find another way, please tell me.