JSONSchema

JSONSchema

OpenAPI "Schema Object"

public enum JSONSchema

See OpenAPI Schema Object.

Inheritance

ComponentDictionaryLocatable, Decodable, Encodable, Equatable, LocallyDereferenceable, JSONSchemaContext

Initializers

init(from:)

public init(from decoder: Decoder) throws

Enumeration Cases

boolean

case boolean(: CoreContext<JSONTypeFormat.BooleanFormat>)

number

case number(: CoreContext<JSONTypeFormat.NumberFormat>, : NumericContext)

integer

case integer(: CoreContext<JSONTypeFormat.IntegerFormat>, : IntegerContext)

string

case string(: CoreContext<JSONTypeFormat.StringFormat>, : StringContext)

object

case object(: CoreContext<JSONTypeFormat.ObjectFormat>, : ObjectContext)

array

case array(: CoreContext<JSONTypeFormat.ArrayFormat>, : ArrayContext)

all

case all(of: [JSONSchema], core: CoreContext<JSONTypeFormat.AnyFormat>)

one

case one(of: [JSONSchema], core: CoreContext<JSONTypeFormat.AnyFormat>)

any

case any(of: [JSONSchema], core: CoreContext<JSONTypeFormat.AnyFormat>)

not

case not(: JSONSchema, core: CoreContext<JSONTypeFormat.AnyFormat>)

reference

case reference(: JSONReference<JSONSchema>)

fragment

Schemas without a type.

case fragment(: CoreContext<JSONTypeFormat.AnyFormat>)

Properties

openAPIComponentsKey

var openAPIComponentsKey: String

openAPIComponentsKeyPath

var openAPIComponentsKeyPath: KeyPath<OpenAPI.Components, OpenAPI.ComponentDictionary<Self>>

jsonTypeFormat

The type and format of the schema.

var jsonTypeFormat: JSONTypeFormat?

jsonType

The fundamental type of the schema.

var jsonType: JSONType?

formatString

The format of the schema as a string value.

var formatString: String?

This can be set even when a schema type has not be specified. If a type has been specified, a type-safe format can be used and retrieved via the jsonTypeFormat property.

required

var required: Bool

description

var description: String?

discriminator

var discriminator: OpenAPI.Discriminator?

nullable

var nullable: Bool

readOnly

var readOnly: Bool

writeOnly

var writeOnly: Bool

deprecated

var deprecated: Bool

title

var title: String?

externalDocs

var externalDocs: OpenAPI.ExternalDocumentation?

allowedValues

var allowedValues: [AnyCodable]?

defaultValue

var defaultValue: AnyCodable?

example

var example: AnyCodable?

isEmpty

Check if this schema is an empty .fragment.

var isEmpty: Bool

A special case of the .fragment schema is the "empty" schema where no information about the schema component is available.

This is equivalent to the following JSON Schema:

{
}

isFragment

Check if this schema is a .fragment.

var isFragment: Bool

isBoolean

Check if a schema is a .boolean.

var isBoolean: Bool

isNumber

Check if a schema is a .number.

var isNumber: Bool

This returns false if the schema is an .integer even though Integer schemas can be easily transformed into Number schemas.

isInteger

Check if a schema is an .integer.

var isInteger: Bool

isString

Check if a schema is a .string.

var isString: Bool

isObject

Check if a schema is an .object.

var isObject: Bool

isArray

Check if a schema is an .array.

var isArray: Bool

isReference

Check if a schema is a .reference.

var isReference: Bool

coreContext

Get the core context most JSONSchemas have.

var coreContext: JSONSchemaContext?

This is the information shared by most schemas.

Notably, reference schemas do not have this core context.

objectContext

Get the context specific to an object schema. If not an object schema, returns nil.

var objectContext: ObjectContext?

arrayContext

Get the context specific to an array schema. If not an array schema, returns nil.

var arrayContext: ArrayContext?

numberContext

Get the context specific to a number schema. If not a number schema, returns nil.

var numberContext: NumericContext?

Although integers are numbers, an integer schema will still return nil when asked for a numberContext.

If you wish to get a NumericContext from an integer schema, take an IntegerContext and explicitly request a NumericContext from it via its numericContext accessor.

integerContext

Get the context specific to an integer schema. If not an integer schema, returns nil.

var integerContext: IntegerContext?

stringContext

Get the context specific to a string schema. If not a string schema, returns nil.

var stringContext: StringContext?

boolean

A required, non-nullable boolean schema.

var boolean: JSONSchema

fragment

A required, non-nullable fragment of a schema.

var fragment: JSONSchema

This is also known as the "empty" schema because its representation in JSON is just an empty object { }.

string

A required, non-nullable string schema.

var string: JSONSchema

number

A required, non-nullable number schema.

var number: JSONSchema

integer

A required, non-nullable integer schema.

var integer: JSONSchema

object

A required, non-nullable object schema.

var object: JSONSchema

array

A required, non-nullable array schema.

var array: JSONSchema

Methods

_dereferenced(in:following:)

Returns a dereferenced schema object if all references in this schema object can be found in the Components Object.

public func _dereferenced(in components: OpenAPI.Components, following references: Set<AnyHashable>) throws -> DereferencedJSONSchema

Throws

ReferenceError.cannotLookupRemoteReference or ReferenceError.missingOnLookup(name:​key:​) depending on whether an unresolvable reference points to another file or just points to a component in the same file that cannot be found in the Components Object.

dereferenced()

Returns a dereferenced schema object if this schema object already does not contain any references.

public func dereferenced() -> DereferencedJSONSchema?

To create a dereferenced schema object from a schema object that does have references, use dereferenced(in:).

optionalSchemaObject()

Return the optional version of this JSONSchema

public func optionalSchemaObject() -> JSONSchema

requiredSchemaObject()

Return the required version of this JSONSchema

public func requiredSchemaObject() -> JSONSchema

nullableSchemaObject()

Return the nullable version of this JSONSchema

public func nullableSchemaObject() -> JSONSchema

with(allowedValues:)

Return a version of this JSONSchema that only allows the given values.

public func with(allowedValues: [AnyCodable]) -> JSONSchema

with(defaultValue:)

Return a version of this JSONSchema that has the given default value.

public func with(defaultValue: AnyCodable) -> JSONSchema

with(example:)

Returns a version of this JSONSchema that has the given example attached.

public func with(example: AnyCodable) throws -> JSONSchema

with(discriminator:)

Returns a version of this JSONSchema that has the given discriminator.

public func with(discriminator: OpenAPI.Discriminator) -> JSONSchema

boolean(format:required:nullable:permissions:deprecated:title:description:discriminator:externalDocs:allowedValues:defaultValue:example:)

Construct a boolean schema.

public static func boolean(format: JSONTypeFormat.BooleanFormat = .unspecified, required: Bool = true, nullable: Bool? = nil, permissions: JSONSchema.CoreContext<JSONTypeFormat.BooleanFormat>.Permissions? = nil, deprecated: Bool? = nil, title: String? = nil, description: String? = nil, discriminator: OpenAPI.Discriminator? = nil, externalDocs: OpenAPI.ExternalDocumentation? = nil, allowedValues: [AnyCodable]? = nil, defaultValue: AnyCodable? = nil, example: AnyCodable? = nil) -> JSONSchema

boolean(format:required:nullable:permissions:deprecated:title:description:discriminator:externalDocs:allowedValues:defaultValue:example:)

Construct a boolean schema passing a variadic list of allowed values.

public static func boolean(format: JSONTypeFormat.BooleanFormat = .unspecified, required: Bool = true, nullable: Bool? = nil, permissions: JSONSchema.CoreContext<JSONTypeFormat.BooleanFormat>.Permissions? = nil, deprecated: Bool? = nil, title: String? = nil, description: String? = nil, discriminator: OpenAPI.Discriminator? = nil, externalDocs: OpenAPI.ExternalDocumentation? = nil, allowedValues: AnyCodable, defaultValue: AnyCodable? = nil, example: AnyCodable? = nil) -> JSONSchema

fragment(format:required:nullable:permissions:deprecated:title:description:discriminator:externalDocs:allowedValues:defaultValue:example:)

Construct a fragment of a schema.

public static func fragment(format: JSONTypeFormat.AnyFormat = .unspecified, required: Bool = true, nullable: Bool? = nil, permissions: JSONSchema.CoreContext<JSONTypeFormat.AnyFormat>.Permissions? = nil, deprecated: Bool? = nil, title: String? = nil, description: String? = nil, discriminator: OpenAPI.Discriminator? = nil, externalDocs: OpenAPI.ExternalDocumentation? = nil, allowedValues: [AnyCodable]? = nil, defaultValue: AnyCodable? = nil, example: AnyCodable? = nil) -> JSONSchema

fragment(format:required:nullable:permissions:deprecated:title:description:discriminator:externalDocs:allowedValues:defaultValue:example:)

Construct a fragment of a schema passing a variadic list of allowed values.

public static func fragment(format: JSONTypeFormat.AnyFormat = .unspecified, required: Bool = true, nullable: Bool? = nil, permissions: JSONSchema.CoreContext<JSONTypeFormat.AnyFormat>.Permissions? = nil, deprecated: Bool? = nil, title: String? = nil, description: String? = nil, discriminator: OpenAPI.Discriminator? = nil, externalDocs: OpenAPI.ExternalDocumentation? = nil, allowedValues: AnyCodable, defaultValue: AnyCodable? = nil, example: AnyCodable? = nil) -> JSONSchema

string(format:required:nullable:permissions:deprecated:title:description:discriminator:externalDocs:minLength:maxLength:pattern:allowedValues:defaultValue:example:)

Construct a string schema.

public static func string(format: JSONTypeFormat.StringFormat = .unspecified, required: Bool = true, nullable: Bool? = nil, permissions: JSONSchema.CoreContext<JSONTypeFormat.StringFormat>.Permissions? = nil, deprecated: Bool? = nil, title: String? = nil, description: String? = nil, discriminator: OpenAPI.Discriminator? = nil, externalDocs: OpenAPI.ExternalDocumentation? = nil, minLength: Int? = nil, maxLength: Int? = nil, pattern: String? = nil, allowedValues: [AnyCodable]? = nil, defaultValue: AnyCodable? = nil, example: AnyCodable? = nil) -> JSONSchema

string(format:required:nullable:permissions:deprecated:title:description:discriminator:externalDocs:minLength:maxLength:pattern:allowedValues:defaultValue:example:)

Construct a string schema passing a variadic list of allowed values.

public static func string(format: JSONTypeFormat.StringFormat = .unspecified, required: Bool = true, nullable: Bool? = nil, permissions: JSONSchema.CoreContext<JSONTypeFormat.StringFormat>.Permissions? = nil, deprecated: Bool? = nil, title: String? = nil, description: String? = nil, discriminator: OpenAPI.Discriminator? = nil, externalDocs: OpenAPI.ExternalDocumentation? = nil, minLength: Int? = nil, maxLength: Int? = nil, pattern: String? = nil, allowedValues: AnyCodable, defaultValue: AnyCodable? = nil, example: AnyCodable? = nil) -> JSONSchema

number(format:required:nullable:permissions:deprecated:title:description:discriminator:externalDocs:multipleOf:maximum:minimum:allowedValues:defaultValue:example:)

Construct a number schema.

public static func number(format: JSONTypeFormat.NumberFormat = .unspecified, required: Bool = true, nullable: Bool? = nil, permissions: JSONSchema.CoreContext<JSONTypeFormat.NumberFormat>.Permissions? = nil, deprecated: Bool? = nil, title: String? = nil, description: String? = nil, discriminator: OpenAPI.Discriminator? = nil, externalDocs: OpenAPI.ExternalDocumentation? = nil, multipleOf: Double? = nil, maximum: (Double, exclusive: Bool)? = nil, minimum: (Double, exclusive: Bool)? = nil, allowedValues: [AnyCodable]? = nil, defaultValue: AnyCodable? = nil, example: AnyCodable? = nil) -> JSONSchema

number(format:required:nullable:permissions:deprecated:title:description:discriminator:externalDocs:multipleOf:maximum:minimum:allowedValues:defaultValue:example:)

Construct a number schema passing a variadic list of allowed values.

public static func number(format: JSONTypeFormat.NumberFormat = .unspecified, required: Bool = true, nullable: Bool? = nil, permissions: JSONSchema.CoreContext<JSONTypeFormat.NumberFormat>.Permissions? = nil, deprecated: Bool? = nil, title: String? = nil, description: String? = nil, discriminator: OpenAPI.Discriminator? = nil, externalDocs: OpenAPI.ExternalDocumentation? = nil, multipleOf: Double? = nil, maximum: (Double, exclusive: Bool)? = nil, minimum: (Double, exclusive: Bool)? = nil, allowedValues: AnyCodable, defaultValue: AnyCodable? = nil, example: AnyCodable? = nil) -> JSONSchema

integer(format:required:nullable:permissions:deprecated:title:description:discriminator:externalDocs:multipleOf:maximum:minimum:allowedValues:defaultValue:example:)

Construct an integer schema.

public static func integer(format: JSONTypeFormat.IntegerFormat = .unspecified, required: Bool = true, nullable: Bool? = nil, permissions: JSONSchema.CoreContext<JSONTypeFormat.IntegerFormat>.Permissions? = nil, deprecated: Bool? = nil, title: String? = nil, description: String? = nil, discriminator: OpenAPI.Discriminator? = nil, externalDocs: OpenAPI.ExternalDocumentation? = nil, multipleOf: Int? = nil, maximum: (Int, exclusive: Bool)? = nil, minimum: (Int, exclusive: Bool)? = nil, allowedValues: [AnyCodable]? = nil, defaultValue: AnyCodable? = nil, example: AnyCodable? = nil) -> JSONSchema

integer(format:required:nullable:permissions:deprecated:title:description:discriminator:externalDocs:multipleOf:maximum:minimum:allowedValues:defaultValue:example:)

Construct an integer schema passing a variadic list of allowed values.

public static func integer(format: JSONTypeFormat.IntegerFormat = .unspecified, required: Bool = true, nullable: Bool? = nil, permissions: JSONSchema.CoreContext<JSONTypeFormat.IntegerFormat>.Permissions? = nil, deprecated: Bool? = nil, title: String? = nil, description: String? = nil, discriminator: OpenAPI.Discriminator? = nil, externalDocs: OpenAPI.ExternalDocumentation? = nil, multipleOf: Int? = nil, maximum: (Int, exclusive: Bool)? = nil, minimum: (Int, exclusive: Bool)? = nil, allowedValues: AnyCodable, defaultValue: AnyCodable? = nil, example: AnyCodable? = nil) -> JSONSchema

object(format:required:nullable:permissions:deprecated:title:description:discriminator:externalDocs:minProperties:maxProperties:properties:additionalProperties:allowedValues:defaultValue:example:)

Construct an objecy schema.

public static func object(format: JSONTypeFormat.ObjectFormat = .unspecified, required: Bool = true, nullable: Bool? = nil, permissions: JSONSchema.CoreContext<JSONTypeFormat.ObjectFormat>.Permissions? = nil, deprecated: Bool? = nil, title: String? = nil, description: String? = nil, discriminator: OpenAPI.Discriminator? = nil, externalDocs: OpenAPI.ExternalDocumentation? = nil, minProperties: Int? = nil, maxProperties: Int? = nil, properties: [String: JSONSchema] = [:], additionalProperties: Either<Bool, JSONSchema>? = nil, allowedValues: [AnyCodable]? = nil, defaultValue: AnyCodable? = nil, example: AnyCodable? = nil) -> JSONSchema

array(format:required:nullable:permissions:deprecated:title:description:discriminator:externalDocs:minItems:maxItems:uniqueItems:items:allowedValues:defaultValue:example:)

Construct an array schema.

public static func array(format: JSONTypeFormat.ArrayFormat = .unspecified, required: Bool = true, nullable: Bool? = nil, permissions: JSONSchema.CoreContext<JSONTypeFormat.ArrayFormat>.Permissions? = nil, deprecated: Bool? = nil, title: String? = nil, description: String? = nil, discriminator: OpenAPI.Discriminator? = nil, externalDocs: OpenAPI.ExternalDocumentation? = nil, minItems: Int? = nil, maxItems: Int? = nil, uniqueItems: Bool? = nil, items: JSONSchema? = nil, allowedValues: [AnyCodable]? = nil, defaultValue: AnyCodable? = nil, example: AnyCodable? = nil) -> JSONSchema

all(of:)

Construct a schema stating all of the given fragment requirements are met.

public static func all(of schemas: [JSONSchema]) -> JSONSchema

all(of:required:title:description:discriminator:)

Construct a schema stating all of the given fragment requirements are met given a discriminator.

public static func all(of schemas: JSONSchema, required: Bool = true, title: String? = nil, description: String? = nil, discriminator: OpenAPI.Discriminator? = nil) -> JSONSchema

one(of:)

Construct a schema stating one of the given schema's requirements are met.

public static func one(of schemas: [JSONSchema]) -> JSONSchema

one(of:required:title:description:discriminator:)

Construct a schema stating one of the given schema's requirements are met given a discriminator.

public static func one(of schemas: JSONSchema, required: Bool = true, title: String? = nil, description: String? = nil, discriminator: OpenAPI.Discriminator? = nil) -> JSONSchema

any(of:)

Construct a schema stating any of the given schema's requirements are met.

public static func any(of schemas: [JSONSchema]) -> JSONSchema

any(of:required:title:description:discriminator:)

Construct a schema stating any of the given schema's requirements are met given a discriminator.

public static func any(of schemas: JSONSchema, required: Bool = true, title: String? = nil, description: String? = nil, discriminator: OpenAPI.Discriminator? = nil) -> JSONSchema

not(_:required:title:description:discriminator:)

Construct a schema stating the given schema's requirements are not met.

public static func not(_ schema: JSONSchema, required: Bool = true, title: String? = nil, description: String? = nil, discriminator: OpenAPI.Discriminator? = nil) -> JSONSchema

Only the schema taken as the first argument is inverted by the not logic. Any other arguments are here to directly describe what this schema is as opposed to what it is not.

encode(to:)

public func encode(to encoder: Encoder) throws

simplified(given:)

Get a simplified DereferencedJSONSchema.

public func simplified(given components: OpenAPI.Components) throws -> DereferencedJSONSchema

A fully simplified JSON Schema is both dereferenced and also reduced to a more normal form where possible.

As an example, many compound schemas can be simplified.

{
    "allOf": [
        { "type": "object", "description": "Hello World" },
        {
            "properties": [
                "name": { "type": "string" }
            ]
        }
    ]
}

simplifies to ->

{
    "type": "object",
    "description": "Hello World",
    "properties": [
        "name": { "type": "string" }
    ]
}

You can create simplified schemas from the DereferencedJSONSchema type with the simplified() method or you can create simplified schemas from the JSONSchema type with the simplified(given:) method (which combines dereferencing and resolving by taking the OpenAPI.Components as input).