Spectral

View Source

Spectral provides type-safe data serialization and deserialization for Elixir types. Currently the focus is on JSON.

  • Type-safe conversion: Convert typed Elixir values to/from external formats such as JSON, ensuring data conforms to the type specification
  • Detailed errors: Get error messages with location information when validation fails
  • Support for complex scenarios: Handles unions, structs, atoms, nested structures, and more

Installation

Add spectral to your list of dependencies in mix.exs:

def deps do
  [
    {:spectral, "~> 0.7.0"}
  ]
end

Usage

Here's how to use Spectral for JSON serialization and deserialization:

Note: Spectral reads type information from compiled beam files, so modules must be defined in files (not in IEx).

# lib/person.ex
defmodule Person do
  defmodule Address do
    defstruct [:street, :city]

    @type t :: %Address{
            street: String.t(),
            city: String.t()
          }
  end

  defstruct [:name, :age, :address]

  @type t :: %Person{
          name: String.t(),
          age: non_neg_integer() | nil,
          address: Address.t() | nil
        }
end
# Encode a struct to JSON
person = %Person{
  name: "Alice",
  age: 30,
  address: %Person.Address{
    street: "Ystader Straße",
    city: "Berlin"
  }
}

with {:ok, json_iodata} <- Spectral.encode(person, Person, :t) do
  IO.iodata_to_binary(json_iodata)
  # Returns: "{\"address\":{\"city\":\"Berlin\",\"street\":\"Ystader Straße\"},\"age\":30,\"name\":\"Alice\"}"
end

# Decode JSON to a struct
json_string = ~s({"name":"Alice","age":30,"address":{"street":"Ystader Straße","city":"Berlin"}})
{:ok, person} = Spectral.decode(json_string, Person, :t)

# Generate a JSON schema
schema_iodata = Spectral.schema(Person, :t)
IO.iodata_to_binary(schema_iodata)

Bang Functions

For convenience, Spectral provides bang versions (!) of all main functions that raise exceptions instead of returning error tuples:

json =
  person
  |> Spectral.encode!(Person, :t)
  |> IO.iodata_to_binary()

person =
  json_string
  |> Spectral.decode!(Person, :t)

schema =
  Person
  |> Spectral.schema(:t)
  |> IO.iodata_to_binary()

Use bang functions when you want exceptions instead of explicit error handling.

Nil Value Handling

Spectral automatically omits nil values from JSON output for optional struct fields:

# Only required fields
person = %Person{name: "Alice"}

with {:ok, json_iodata} <- Spectral.encode(person, Person, :t) do
  IO.iodata_to_binary(json_iodata)
  # Returns: "{\"name\":\"Alice\"}" (age and address are omitted)
end

# When decoding, both missing fields and explicit null values become nil in structs
Spectral.decode(~s({"name":"Alice"}), Person, :t)
# Returns: {:ok, %Person{name: "Alice", age: nil, address: nil}}

Spectral.decode(~s({"name":"Alice","age":null,"address":null}), Person, :t)
# Returns: {:ok, %Person{name: "Alice", age: nil, address: nil}}

Extra Fields Handling

When decoding JSON into Elixir structs, extra fields that are not defined in the type specification are silently ignored. This enables forward compatibility and flexible API evolution:

# JSON with extra fields not in the Person type
json = ~s({"name":"Alice","age":30,"unknown_field":"ignored"})

Spectral.decode(json, Person, :t)
# Returns: {:ok, %Person{name: "Alice", age: 30, address: nil}}
# Extra fields are discarded without errors

This permissive behavior allows your application to accept JSON from newer API versions without breaking, as long as all required fields are present.

Data Serialization API

The main functions for JSON serialization and deserialization (pipe-friendly):

# Regular versions (return tuples)
Spectral.encode(data, module, type_ref, format \\ :json) ::
    {:ok, iodata()} | {:error, [%Spectral.Error{}]}

Spectral.encode!(data, module, type_ref, format \\ :json) :: iodata()

Spectral.decode(data, module, type_ref, format \\ :json) ::
    {:ok, dynamic()} | {:error, [%Spectral.Error{}]}

Spectral.decode!(data, module, type_ref, format \\ :json) :: dynamic()

Parameters:

  • data - The data to encode/decode (Elixir value for encode, binary/string for decode)
  • module - The module where the type is defined (e.g., Person)
  • type_ref - The type reference, typically an atom like :t for the @type t definition
  • format - (optional) The data format: :json (default), :binary_string, or :string

Schema API

Generate schemas from your type definitions:

Spectral.schema(module, type_ref, format \\ :json_schema) :: iodata()

Parameters:

  • module - The module where the type is defined
  • type_ref - The type reference
  • format - (optional) Schema format, currently supports :json_schema (default)

Documenting Types with spectral

You can add JSON Schema documentation (title, description, examples) to your types using the spectral macro:

defmodule Person do
  use Spectral

  defstruct [:name, :age]

  spectral title: "Person", description: "A person with name and age"
  @type t :: %Person{
    name: String.t(),
    age: non_neg_integer() | nil
  }
end

Place the spectral call before the @type definition it documents. When you generate a JSON schema, it will include the title and description:

schema = Spectral.schema(Person, :t) |> IO.iodata_to_binary() |> Jason.decode!()
# %{
#   "title" => "Person",
#   "description" => "A person with name and age",
#   "type" => "object",
#   ...
# }

Supported fields:

  • title - A short title for the type
  • description - A longer description of what the type represents
  • examples - A list of example values (not yet fully supported)

Multiple types in one module:

If you have multiple types in a module, you only need to document the types you want. Types without spectral calls won't have title/description in their schemas:

defmodule MyModule do
  use Spectral

  # Documented type
  spectral title: "Public API", description: "The public interface"
  @type public_api :: map()

  # Undocumented type - no spectral call needed
  @type internal_type :: atom()
end

Documenting Functions (Endpoint Metadata)

The spectral macro also works before @spec definitions to attach OpenAPI endpoint documentation to functions:

defmodule MyController do
  use Spectral

  spectral summary: "Get user", description: "Returns a user by ID"
  @spec show(map(), map()) :: map()
  def show(_conn, _params), do: %{}
end

Supported fields:

  • summary - Short summary of the endpoint operation
  • description - Longer description of the operation
  • deprecated - Whether the endpoint is deprecated (boolean)

This metadata is used by Spectral.OpenAPI.endpoint/5 to automatically populate OpenAPI operation fields — see the OpenAPI section below.

OpenAPI Specification

Spectral can generate complete OpenAPI 3.0 specifications for your REST APIs. This provides interactive documentation, client generation, and API testing tools.

OpenAPI Builder API

The API uses a fluent builder pattern for constructing endpoints and responses. While experimental and subject to change, it's designed to be used by web framework developers.

Building Responses

Responses are constructed using a builder pattern:

Code.ensure_loaded!(Person)

# Simple response
user_not_found_response =
  Spectral.OpenAPI.response(404, "User not found")

# Response with body
user_found_response =
  Spectral.OpenAPI.response(200, "User found")
  |> Spectral.OpenAPI.response_with_body(Person, :t)

user_created_response =
  Spectral.OpenAPI.response(201, "User created")
  |> Spectral.OpenAPI.response_with_body(
    Person,
    {:type, :t, 0}
  )

users_found_response =
  Spectral.OpenAPI.response(200, "Users found")
  |> Spectral.OpenAPI.response_with_body(
    Person,
    {:type, :persons, 0}
  )

# Response with response header
response_with_headers =
  Spectral.OpenAPI.response(200, "Success")
  |> Spectral.OpenAPI.response_with_body(Person, :t)
  |> Spectral.OpenAPI.response_with_header(
    "X-Rate-Limit",
    :t,
    %{
      description: "Requests remaining",
      required: false,
      schema: :integer
    }
  )

Building Endpoints

Endpoints are built by combining the endpoint definition with responses, request bodies, and parameters.

Use endpoint/5 to automatically pull the endpoint documentation from a function's spectral/1 annotation:

# Documentation comes from the spectral/1 annotation on MyController.show/2
user_get_endpoint =
  Spectral.OpenAPI.endpoint(:get, "/users/{id}", MyController, :show, 2)
  |> Spectral.OpenAPI.add_response(user_found_response)

Or use endpoint/3 to pass documentation inline:

user_get_endpoint =
  Spectral.OpenAPI.endpoint(:get, "/users/{id}", %{summary: "Get user by ID"})
  |> Spectral.OpenAPI.with_parameter(Person, %{
    name: "id",
    in: :path,
    required: true,
    schema: :string,
    description: "The user ID"
  })
  |> Spectral.OpenAPI.add_response(user_found_response)
  |> Spectral.OpenAPI.add_response(user_not_found_response)


# Add request body (for POST, PUT, PATCH)
user_create_endpoint =
  Spectral.OpenAPI.endpoint(:post, "/users")
  |> Spectral.OpenAPI.with_request_body(
    Person,
    {:type, :t, 0},
    %{description: "User to create"}
  )
  |> Spectral.OpenAPI.add_response(user_created_response)

# Override content type (defaults to "application/json")
user_create_xml_endpoint =
  Spectral.OpenAPI.endpoint(:post, "/users")
  |> Spectral.OpenAPI.with_request_body(
    Person,
    {:type, :t, 0},
    %{content_type: "application/xml", description: "User to create"}
  )
  |> Spectral.OpenAPI.add_response(user_created_response)

# Add parameters
user_search_endpoint =
  Spectral.OpenAPI.endpoint(:get, "/users")
  |> Spectral.OpenAPI.with_parameter(Person, %{
    name: "search",
    in: :query,
    required: false,
    schema: :search
  })
  |> Spectral.OpenAPI.add_response(users_found_response)

Generating the OpenAPI Specification

Combine all endpoints into a complete OpenAPI spec:

metadata = %{
  title: "My API",
  version: "1.0.0",
  # Optional fields:
  summary: "Short summary of the API",
  description: "Longer description of the API",
  terms_of_service: "https://example.com/terms",
  contact: %{name: "Support", url: "https://example.com/support", email: "support@example.com"},
  license: %{name: "MIT", url: "https://opensource.org/licenses/MIT"},
  servers: [%{url: "https://api.example.com", description: "Production"}]
}


endpoints = [
  #user_get_endpoint,
  user_create_endpoint,
  #user_search_endpoint
]

{:ok, openapi_spec} =
  Spectral.OpenAPI.endpoints_to_openapi(metadata, endpoints)

IO.inspect(openapi_spec, pretty: true)

Requirements

  • Erlang/OTP 27+: Spectral requires Erlang/OTP version 27 or later (required by the underlying spectra library)
  • Compilation: Modules must be compiled with debug_info for Spectral to extract type information. This is enabled by default in Mix projects.

Error Handling

Spectral provides two types of functions with different error handling strategies:

Normal Functions

The encoding and decoding functions (encode/3-4, decode/3-4) use a dual error handling approach:

Data validation errors return {:error, [%Spectral.Error{}]} tuples:

  • Type mismatches (e.g., string when integer expected)
  • Missing required fields
  • Invalid data structure
  • Decoding failures

Use with for clean error handling:

bad_json = ~s({"name":"Alice","age":"not a number"})

with {:ok, person} <- Spectral.decode(bad_json, Person, :t) do
  process_person(person)
end

Type and configuration errors raise exceptions:

  • Module not found, unloaded, or compiled without debug_info
  • Type not found in the specified module
  • Unsupported types used (e.g., pid(), port(), tuple())

These exceptions indicate problems with your application's configuration or type definitions, not with the data being processed.

Bang Functions

The bang versions (encode!/3-4, decode!/3-4) always raise exceptions for any error:

person =
  bad_json
  |> Spectral.decode!(Person, :t)
  |> process_person()

Use bang functions when you want to propagate all errors as exceptions, simplifying pipelines but requiring try/rescue for error handling.

Schema Generation

The schema/2-3 function returns the schema directly as iodata() without wrapping it in a result tuple:

schema = Spectral.schema(Person, :t)
IO.iodata_to_binary(schema)

Schema generation may still raise exceptions for type and configuration errors (module not found, type not found, etc.).

Error Structure

Each Spectral.Error struct represents a single error with the following fields:

  • location - Path showing where the error occurred (e.g., ["user", "age"])
  • type - Error type: :decode_error, :type_mismatch, :no_match, :missing_data, :not_matched_fields
  • context - Additional context information about the error
  • message - Human-readable error message (auto-generated)

Functions return {:error, [%Spectral.Error{}]} - a list of error structs:

{:error, [
  %Spectral.Error{
    location: ["user", "age"],
    type: :type_mismatch,
    context: %{expected: :integer, got: "not a number"},
    message: "type_mismatch at user.age"
  }
]}

Special Handling

nil Values

In Elixir structs, nil values are handled specially:

  • When encoding to JSON, struct fields with nil values are omitted from the output if the type includes nil as a valid value
  • When decoding from JSON, missing fields become nil if the type specification allows it

Example:

@type t :: %Person{
  name: String.t(),
  age: non_neg_integer() | nil  # nil is allowed
}

dynamic(), term() and any()

When using types with dynamic(), term(), or any() in your type specifications, Spectral will not reject any data, which means it can return data that may not be valid JSON.

Note: Spectral uses dynamic() for runtime-determined types in its own API, following Erlang's gradual typing conventions.

Unsupported Types

For JSON serialization and schema generation, the following Erlang/Elixir types are not supported:

  • pid(), port(), reference() - Cannot be serialized to JSON
  • tuple() (generic tuples without specific structure)
  • Function types - Cannot be serialized
  • spectra - The underlying Erlang library that powers Spectral

Development Status

This library is under active development. APIs may change in future versions.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

See LICENSE.md for details.