open_api_spex v1.1.4 OpenApiSpex.Schema behaviour View Source

Defines the OpenApiSpex.Schema.t type and operations for casting and validating against a schema.

Link to this section Summary

Functions

Cast a simple value to the elixir type defined by a schema

Validate a value against a Schema

Callbacks

A module implementing the OpenApiSpex.Schema behaviour should export a schema/0 function that produces an OpenApiSpex.Schema struct

Link to this section Types

Link to this type t() View Source
t() :: %OpenApiSpex.Schema{maximum: number() | nil, minProperties: integer() | nil, externalDocs: OpenApiSpex.ExternalDocumentation.t() | nil, title: String.t(), maxLength: integer() | nil, minimum: number() | nil, pattern: String.t() | Regex.t() | nil, minLength: integer() | nil, nullable: boolean() | nil, readOnly: boolean() | nil, items: OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t() | nil, not: OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t() | nil, maxItems: integer() | nil, deprecated: boolean() | nil, example: any(), xml: OpenApiSpex.Xml.t() | nil, multipleOf: number() | nil, oneOf: [OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t()] | nil, description: String.t(), allOf: [OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t()] | nil, exclusiveMinimum: boolean() | nil, "x-struct": module() | nil, additionalProperties: boolean() | OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t() | nil, required: [String.t()] | nil, writeOnly: boolean() | nil, maxProperties: integer() | nil, format: String.t() | nil, minItems: integer() | nil, enum: [String.t()] | nil, anyOf: [OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t()] | nil, exclusiveMaximum: boolean() | nil, discriminator: OpenApiSpex.Discriminator.t() | nil, uniqueItems: boolean() | nil, default: any() | nil, type: atom(), properties: %{optional(atom()) => OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t()} | nil}

Schema Object

The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the JSON Schema Specification Wright Draft 00.

Example

alias OpenApiSpex.Schema

%Schema{
  title: "User",
  type: :object,
  properties: %{
    id: %Schema{type: :integer, minimum: 1},
    name: %Schema{type: :string, pattern: "[a-zA-Z][a-zA-Z0-9_]+"},
    email: %Scheam{type: :string, format: :email},
    last_login: %Schema{type: :string, format: :"date-time"}
  },
  required: [:name, :email],
  example: %{
    "name" => "joe",
    "email" => "joe@gmail.com"
  }
}

Link to this section Functions

Link to this function cast(schema, value, schemas) View Source
cast(OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t(), any(), %{optional(String.t()) => OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t()}) ::
  {:ok, any()} |
  {:error, String.t()}

Cast a simple value to the elixir type defined by a schema.

By default, object types are cast to maps, however if the “x-struct” attribute is set in the schema, the result will be constructed as an instance of the given struct type.

Examples

iex> OpenApiSpex.Schema.cast(%Schema{type: :integer}, "123", %{})
{:ok, 123}

iex> {:ok, dt = %DateTime{}} = OpenApiSpex.Schema.cast(%Schema{type: :string, format: :"date-time"}, "2018-04-02T13:44:55Z", %{})
...> dt |> DateTime.to_iso8601()
"2018-04-02T13:44:55Z"
Link to this function validate(schema, val, schemas) View Source
validate(OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t(), any(), %{optional(String.t()) => OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t()}) ::
  :ok |
  {:error, String.t()}

Validate a value against a Schema.

This expects that the value has already been cast to the appropriate data type.

Examples

iex> OpenApiSpex.Schema.validate(%OpenApiSpex.Schema{type: :integer, minimum: 5}, 3, %{})
{:error, "#: 3 is smaller than minimum 5"}

iex> OpenApiSpex.Schema.validate(%OpenApiSpex.Schema{type: :string, pattern: "(.*)@(.*)"}, "joe@gmail.com", %{})
:ok

iex> OpenApiSpex.Schema.validate(%OpenApiSpex.Schema{type: :string, pattern: "(.*)@(.*)"}, "joegmail.com", %{})
{:error, "#: Value does not match pattern: (.*)@(.*)"}
Link to this function validate(ref, val, path, schemas) View Source
validate(OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t(), any(), String.t(), %{optional(String.t()) => OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t()}) ::
  :ok |
  {:error, String.t()}

Link to this section Callbacks

A module implementing the OpenApiSpex.Schema behaviour should export a schema/0 function that produces an OpenApiSpex.Schema struct.