Rolodex v0.6.0 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:
is_schema_module?/1
- determines if the provided item is a module that has defined a reuseable schemato_map/1
- serializes a schema module into a map for use by aRolodex.Processor
behaviourget_refs/1
- traverses a schema and searches for any nested schemas within
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
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 nametype
- either an atom or another Rolodex.Schema moduleopts
- a keyword list of options, looks fordesc
andof
(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
get_refs(schema)
Traverses a serialized Schema and collects any nested references to other
Schemas within. See Rolodex.Field.get_refs/1
for more info.
is_schema_module?(item)
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
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 nameopts
- a keyword list of options (currently, only looks for adesc
key)block
- the inner schema definition with one or more calls tofield/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
to_map(schema)
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}
]
}
}
}