Validation

Validation

Holds a function to determine if a validation applies (predicate) and a function that applies a validation (validate).

public struct Validation<Subject: Validatable> 

Initializers

init(check:when:)

Create a Validation that appllies to values of type Subject.

public init(
        check validate: @escaping (ValidationContext<Subject>) -> [ValidationError],
        when predicate: @escaping (ValidationContext<Subject>) -> Bool = { _ in true }
    ) 

You can return any number of errors from your validate function, each with its own description of a problem. Add an optional predicate to apply your validation to a subset of all values of the type your validate method operates on.

Parameters

• validate: A function taking validation contexts containing subjects of type Subject and validating them. This function must return an array of errors. If validation succeeds, return an empty array.
• predicate: A function returning true if this validator should run against the given value.

init(description:check:when:)

Create a Validation with a single error that applies to values of type Subject.

public init(
        description: String,
        check validate: @escaping (ValidationContext<Subject>) -> Bool,
        when predicate: @escaping (ValidationContext<Subject>) -> Bool = { _ in true }
    ) 

This version of the initializer assumes only one error can occur for this validation and in exchange you can frontload the description of the validation and simplify the body of the validate method to just return false if the value is invalid.

Parameters

• description: A description of the correct state described by the validate function. Upon failure, the error will read "Failed to satisfy: ".
• validate: A function taking validation contexts containing subjects of type Subject and validating them. This function returns true if validation succeeds and false if it fails.
• predicate: A function returning true if this validator should run against the given value.

Properties

documentContainsPaths

Validate the OpenAPI Document has at least one path in its PathItem.Map.

public static var documentContainsPaths: Validation<OpenAPI.PathItem.Map> 

The OpenAPI Specifcation does not require that the document contain any paths for security reasons but documentation that is public in nature might only ever have an empty PathItem.Map in error.

pathsContainOperations

Validate the OpenAPI Document's PathItems all have at least one operation.

public static var pathsContainOperations: Validation<OpenAPI.PathItem> 

The OpenAPI Specifcation does not require that path items contain any operations for security reasons but documentation that is public in nature might only ever have a PathItem with no operations in error.

schemaComponentsAreDefined

Validate the OpenAPI Document's JSONSchemas all have at least one defining characteristic.

public static var schemaComponentsAreDefined: Validation<JSONSchema> 

The JSON Schema Specifcation does not require that components have any defining characteristics. An "empty" schema component can be written as follows:

{
}

It is reasonable, however, to want to validate that all schema components are non-empty and therefore offer some value to the consumer/reader of the OpenAPI documentation beyond just "this property exists."

pathParametersAreDefined

Validate that any Parameters in the path of any endpoint are documented. In other words, if a path contains variables (i.e. "{variable}") then there are corresponding parameters entries in the PathItem or Operation for each endpoint.

public static var pathParametersAreDefined: Validation<OpenAPI.PathItem.Map> 

In order to gain easy access to both the path (where the variable placeholders live) and the parameter definitions, this validation runs once per document and performs a loop over each endpoint in the document.

serverVariablesAreDefined

Validate that all Server Objects define all of the variables found in their URL Templates.

public static var serverVariablesAreDefined: Validation<OpenAPI.Server> 

For example, a server URL Template of {scheme}://website.com/{path} would fail this validation if either "scheme" or "path" were not found in the Server Object's variables dictionary.

operationsContainResponses

Validate the OpenAPI Document's Operations all have at least one response.

public static var operationsContainResponses: Validation<OpenAPI.Response.Map> 

The OpenAPI Specifcation requires that Responses Objects contain at least one response. The specification recommends that if there is only one response then it be a successful response.

documentTagNamesAreUnique

Validate that the OpenAPI Document's Tags all have unique names.

public static var documentTagNamesAreUnique: Validation<OpenAPI.Document> 

The OpenAPI Specifcation requires that tag names on the Document are unique.

pathItemParametersAreUnique

Validate that all OpenAPI Path Items have no duplicate parameters defined within them.

public static var pathItemParametersAreUnique: Validation<OpenAPI.PathItem> 

A Path Item Parameter's identity is defined as the pairing of its name and location.

The OpenAPI Specification requires that these parameters are unique.

operationParametersAreUnique

Validate that all OpenAPI Operations have no duplicate parameters defined within them.

public static var operationParametersAreUnique: Validation<OpenAPI.Operation> 

An Operation's Parameter's identity is defined as the pairing of its name and location.

The OpenAPI Specification requires that these parameters are unique.

operationIdsAreUnique

Validate that all OpenAPI Operation Ids are unique across the whole Document.

public static var operationIdsAreUnique: Validation<OpenAPI.Document> 

The OpenAPI Specification requires that Operation Ids are unique.

schemaReferencesAreValid

Validate that all JSONSchema references are found in the document's components dictionary.

public static var schemaReferencesAreValid: Validation<JSONReference<JSONSchema>> 

responseReferencesAreValid

Validate that all Response references are found in the document's components dictionary.

public static var responseReferencesAreValid: Validation<JSONReference<OpenAPI.Response>> 

parameterReferencesAreValid

Validate that all Parameter references are found in the document's components dictionary.

public static var parameterReferencesAreValid: Validation<JSONReference<OpenAPI.Parameter>> 

exampleReferencesAreValid

Validate that all Example references are found in the document's components dictionary.

public static var exampleReferencesAreValid: Validation<JSONReference<OpenAPI.Example>> 

requestReferencesAreValid

Validate that all Request references are found in the document's components dictionary.

public static var requestReferencesAreValid: Validation<JSONReference<OpenAPI.Request>> 

headerReferencesAreValid

Validate that all Header references are found in the document's components dictionary.

public static var headerReferencesAreValid: Validation<JSONReference<OpenAPI.Header>> 

validate

Applies validation on type Subject. Throws if validation fails.

public let validate: (ValidationContext<Subject>) -> [ValidationError]

The context includes

• The entire OpenAPI.Document

• A value of the type in which this validator specializes.

• The coding path where the validation is occurring.

predicate

Returns true if this validator should apply to the given value of type Subject.

public let predicate: (ValidationContext<Subject>) -> Bool

The context includes

• The entire OpenAPI.Document

• A value of the type in which this validator specializes.

• The coding path where the validation is occurring.

Methods

apply(to:at:in:)

Apply the validation to the given value if the predicate returns true.

public func apply(to subject: Subject, at codingPath: [CodingKey], in document: OpenAPI.Document) -> [ValidationError]