JSONSpec

Elixir typespec syntax → JSON Schema, at compile time.

Write familiar Elixir types, get a JSON Schema map with zero runtime cost.

import JSONSpec

schema(%{
  required(:location) => String.t(),
  optional(:units) => :celsius | :fahrenheit
})

# => %{
#   "type" => "object",
#   "properties" => %{
#     "location" => %{"type" => "string"},
#     "units" => %{"type" => "string", "enum" => ["celsius", "fahrenheit"]}
#   },
#   "required" => ["location"],
#   "additionalProperties" => false
# }

Installation

def deps do
  [{:json_spec, "~> 1.0"}]
end

Usage

Objects

Keyword-style keys are required by default:

schema(%{name: String.t(), age: integer()})
# Both "name" and "age" in "required"

Use optional() / required() with arrow syntax for explicit control:

schema(%{
  required(:name) => String.t(),
  optional(:email) => String.t()
})

Or use | nil to mark a field as optional:

schema(%{name: String.t(), email: String.t() | nil})
# Only "name" in "required"

Descriptions

schema(
  %{required(:location) => String.t(), optional(:units) => :celsius | :fahrenheit},
  doc: [location: "City name", units: "Temperature units"]
)

Enums

Unions of atoms become "enum":

schema(:active | :inactive | :pending)
# => %{"type" => "string", "enum" => ["active", "inactive", "pending"]}

Arrays

schema([String.t()])
# => %{"type" => "array", "items" => %{"type" => "string"}}

schema([%{id: integer(), name: String.t()}])
# Array of objects

Nesting

schema(%{
  user: %{
    name: String.t(),
    address: %{city: String.t(), zip: String.t()}
  }
})

Type mapping

Use with LLM tools

JSONSpec pairs well with ReqLLM:

import JSONSpec

Tool.new!(
  name: "get_weather",
  description: "Get current weather for a location",
  parameter_schema: schema(
    %{
      required(:location) => String.t(),
      optional(:units) => :celsius | :fahrenheit
    },
    doc: [location: "City name", units: "Temperature units"]
  ),
  callback: {WeatherService, :get_current_weather}
)

License

MIT