Supporting custom types

[WoobaWooba]

Hi,

I'm new to OpenAPI and we're using for a project where we have our custom data types.

I would like to know if it would be possible to use an UI implementation of the OpenAPI and
have it render the custom data type. For example, I could use this json,

{ "varName":{ "type": "customDataType" } }

and have it rendered as it it were a string or number or any of the other supported types by OA.

P.S.: We could use objects but we would still have to fall back to the OpenAPI data types, which is something we want to avoid.

Thanks

[flaksp]

OpenAPI 3.1 or newer uses JSON Schema (draft 2020-12) spec to define schemas.

The type keyword in JSON Schema defines name of the type that may appear in JSON, this is what the spec says:

The value of this keyword MUST be either a string or an array. If it is an array, elements of the array MUST be strings and MUST be unique.

String values MUST be one of the six primitive types ("null", "boolean", "object", "array", "number", or "string"), or "integer" which matches any number with a zero fractional part.

If type keyword will contain something unexpected, it will lead to invalid JSON Schema, so existing tools won't understand it. This is because in JSON we don't have types named customDataType from your example, we have only nulls, booleans, objects, arrays, numbers and strings.

If you want to specify some data type that has some semantics behind it, you may want to use format keyword. It may be used to describe dates, emails, IP addresses, URIs, etc. Full list of pre-defined data types available in 7.3 "Defined Formats" section of the JSON Schema Validation spec. OpenAPI also defines its own set of pre-defined data types in 4.4 "Data Types" section of the spec.

If pre-defined data types are not enough for you, you are allowed to use your own data types, but there are no guarantees implementations you use will support them as you expect.

Valid example of a schema with format keyword:

{
  "type": "string",
  "format": "email"
}

It's also possible to reuse schemas with $ref keyword.

You may define your schema once in Components Object:

{
  "openapi": "3.1.0",
  "components": {
    "schemas": {
      "Email": {
        "type": "string",
        "format": "email"
      }
    }
  }
}

And then reuse it inside your OpenAPI document with $ref:

{
  "primaryEmail": { "$ref": "#/components/schemas/Email" }
}

[handrews]

This was answered, and type is governed by JSON Schema rather than OpenAPI. We definitely will not be introducing any incompatibilities involving such a core keyword, especially after going to great lengths to resolve all JSON Schema incompatibilities in OAS 3.1. Closing.