JSONSchema

JSONSchema

OpenAPI "Schema Object"

public enum JSONSchema: Equatable, JSONSchemaContext 

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

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

array

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

all

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

one

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

any

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

not

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

reference

case reference(JSONReference<JSONSchema>)

fragment

Schemas without a type.

case fragment(CoreContext<JSONTypeFormat.AnyFormat>)

Properties

openAPIComponentsKey

public static var openAPIComponentsKey: String 

openAPIComponentsKeyPath

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

jsonTypeFormat

The type and format of the schema.

public var jsonTypeFormat: JSONTypeFormat? 

jsonType

The fundamental type of the schema.

public var jsonType: JSONType? 

formatString

The format of the schema as a string value.

public 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

public var required: Bool 

description

public var description: String? 

discriminator

public var discriminator: OpenAPI.Discriminator? 

nullable

public var nullable: Bool 

readOnly

public var readOnly: Bool 

writeOnly

public var writeOnly: Bool 

deprecated

public var deprecated: Bool 

title

public var title: String? 

externalDocs

public var externalDocs: OpenAPI.ExternalDocumentation? 

allowedValues

public var allowedValues: [AnyCodable]? 

defaultValue

public var defaultValue: AnyCodable? 

example

public var example: AnyCodable? 

isEmpty

Check if this schema is an empty .fragment.

public 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.

public var isFragment: Bool 

isBoolean

Check if a schema is a .boolean.

public var isBoolean: Bool 

isNumber

Check if a schema is a .number.

public 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.

public var isInteger: Bool 

isString

Check if a schema is a .string.

public var isString: Bool 

isObject

Check if a schema is an .object.

public var isObject: Bool 

isArray

Check if a schema is an .array.

public var isArray: Bool 

isReference

Check if a schema is a .reference.

public var isReference: Bool 

coreContext

Get the core context most JSONSchemas have.

public 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.

public var objectContext: ObjectContext? 

arrayContext

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

public var arrayContext: ArrayContext? 

numberContext

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

public 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.

public var integerContext: IntegerContext? 

stringContext

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

public var stringContext: StringContext? 

boolean

A required, non-nullable boolean schema.

public static var boolean: JSONSchema 

fragment

A required, non-nullable fragment of a schema.

public static 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.

public static var string: JSONSchema 

number

A required, non-nullable number schema.

public static var number: JSONSchema 

integer

A required, non-nullable integer schema.

public static var integer: JSONSchema 

object

A required, non-nullable object schema.

public static var object: JSONSchema 

array

A required, non-nullable array schema.

public static var array: JSONSchema 

Methods

_dereferenced(in:following:dereferencedFromComponentNamed:)

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>,
        dereferencedFromComponentNamed name: String?
    ) throws -> DereferencedJSONSchema 

_dereferenced(in:following:) is meant for internal use but this type gets a public-facing dereferenced(in:) function for free from the LocallyDereferenceable protocol. For all external uses, call dereferenced(in:).

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).