How to define UUID property in JSON Schema and Open API (OAS)

jsonschema openapi
Slava Fomin II picture Slava Fomin II · May 6, 2018 · Viewed 21.4k times · Source

When using JSON Schema and Open API specification (OAS) to document a REST API, how do I define the UUID property?

Answer

Helen picture Helen · May 7, 2018

There's no built-in type for UUID, but the OpenAPI Specification suggests using

type: string
format: uuid

From the Data Types section (emphasis mine):

Primitives have an optional modifier property: format. OAS uses several known formats to define in fine detail the data type being used. However, to support documentation needs, the format property is an open string-valued property, and can have any value. Formats such as "email", "uuid", and so on, MAY be used even though undefined by this specification.

For example, Swagger Codegen maps format: uuid to System.Guid in C# or java.util.UUID in Java. Tools that don't support format: uuid will handle it as just type: string.

Related questions

Tool to generate JSON schema from JSON data

We have this json schema draft. I would like to get a sample of my JSON data and generate a skeleton for the JSON schema, that I can rework manually, adding things like description, required, etc, which can not be …

Read More
Generate Json schema from XML schema (XSD)

Does anybody know how to generate a JSON schema from a existing XML schema (XSD file)? Are there any tools available for this?

Read More
Generate JSON schema from Java class

I have a POJO class: public class Stock { int id; String name; Date date; } Are there any annotations or development framework/API that can convert POJO to JSON schema like below: {"id": { "type" : "int" }, "name":{ "type" : "string" } "date":{ "type" : "Date" } } …

Read More