Rolodex v0.6.1 Rolodex.Schema

Exposes functions and macros for defining reusable parameter schemas.

It includes two macros. Used together, you can setup a reusable schema:

It also exposes the following functions:

Link to this section Summary

Functions

Adds a new field to the schema. Will generate a method __field__/1 where the one argument is the field identifier. This can be used to fetch the field metadata later

Traverses a serialized Schema and collects any nested references to other Schemas within. See Rolodex.Field.get_refs/1 for more info

Determines if an arbitrary item is a module that has defined a reusable schema via Rolodex.Schema macros

Opens up the schema definition for the current module. Will name the schema and generate metadata for the schema based on subsequent calls to field/3

Serializes the Rolodex.Schema metadata into a formatted map

Link to this section Functions

Link to this macro

field(identifier, type, opts \\ []) (macro)

Adds a new field to the schema. Will generate a method __field__/1 where the one argument is the field identifier. This can be used to fetch the field metadata later.

Accepts

  • identifier - field name
  • type - either an atom or another Rolodex.Schema module
  • opts - a keyword list of options, looks for desc and of (for array types)

Example

defmodule MySchema do
  use Rolodex.Schema

  schema "MySchema", desc: "Example schema" do
    # Atomic field with no description
    field :id, :uuid

    # Atomic field with a description
    field :name, :string, desc: "The object's name"

    # A field that refers to another, nested object
    field :other, OtherSchema

    # A field that is an array of items of one-or-more types
    field :multi, :list, of: [:string, OtherSchema]

    # A field that is one of the possible provided types
    field :any, :one_of, of: [:string, OtherSchema]
  end
end
Link to this function

get_refs(schema)
get_refs(module()) :: [module()]

Traverses a serialized Schema and collects any nested references to other Schemas within. See Rolodex.Field.get_refs/1 for more info.

Link to this function

is_schema_module?(item)
is_schema_module?(any()) :: boolean()

Determines if an arbitrary item is a module that has defined a reusable schema via Rolodex.Schema macros

Example

iex> defmodule SimpleSchema do
...>   use Rolodex.Schema
...>   schema "SimpleSchema", desc: "Demo schema" do
...>     field :id, :uuid
...>   end
...> end
iex>
iex> # Validating a schema module
iex> Rolodex.Schema.is_schema_module?(SimpleSchema)
true
iex> # Validating some other module
iex> Rolodex.Schema.is_schema_module?(OtherModule)
false
Link to this macro

schema(name, opts \\ [], list) (macro)

Opens up the schema definition for the current module. Will name the schema and generate metadata for the schema based on subsequent calls to field/3

Accepts

  • name - the schema name
  • opts - a keyword list of options (currently, only looks for a desc key)
  • block - the inner schema definition with one or more calls to field/3

Example

defmodule MySchema do
  use Rolodex.Schema

  schema "MySchema", desc: "Example schema" do
    # Atomic field with no description
    field :id, :uuid

    # Atomic field with a description
    field :name, :string, desc: "The object's name"

    # A field that refers to another, nested object
    field :other, OtherSchema

    # A field that is an array of items of one-or-more types
    field :multi, :list, of: [:string, OtherSchema]

    # A field that is one of the possible provided types
    field :any, :one_of, of: [:string, OtherSchema]
  end
end
Link to this function

to_map(schema)
to_map(module()) :: map()

Serializes the Rolodex.Schema metadata into a formatted map.

Example

iex> defmodule OtherSchema do
...>   use Rolodex.Schema
...>
...>   schema "OtherSchema" do
...>     field :id, :uuid
...>   end
...> end
iex>
iex> defmodule MySchema do
...>   use Rolodex.Schema
...>
...>   schema "MySchema", desc: "An example" do
...>     # Atomic field with no description
...>     field :id, :uuid
...>
...>     # Atomic field with a description
...>     field :name, :string, desc: "The schema's name"
...>
...>     # A field that refers to another, nested object
...>     field :other, OtherSchema
...>
...>     # A field that is an array of items of one-or-more types
...>     field :multi, :list, of: [:string, OtherSchema]
...>
...>     # A field that is one of the possible provided types
...>     field :any, :one_of, of: [:string, OtherSchema]
...>   end
...> end
iex>
iex> Rolodex.Schema.to_map(MySchema)
%{
  type: :object,
  desc: "An example",
  properties: %{
    id: %{type: :uuid},
    name: %{desc: "The schema's name", type: :string},
    other: %{type: :ref, ref: Rolodex.SchemaTest.OtherSchema},
    multi: %{
      type: :list,
      of: [
        %{type: :string},
        %{type: :ref, ref: Rolodex.SchemaTest.OtherSchema}
      ]
    },
    any: %{
      type: :one_of,
      of: [
        %{type: :string},
        %{type: :ref, ref: Rolodex.SchemaTest.OtherSchema}
      ]
    }
  }
}