Hello, sorry to be spammy but I love working on JSV, my JSON Schema Validator library.

This is a small release with three important things:

• Module-based schemas now need to export a json_schema/0 function instead of a schema/0 function. This makes more sense since we are starting to export json_schemas from other modules like Ecto schema modules. A generic schema/0 function is confusing in that case. Codebases using the old callback will still work, but a warning will be emitted.

  Example:

  defmodule ItemModule do
    def json_schema do
      %{type: :string}
    end
  end
  
  schema = %{type: :array, items: ItemModule} 
  
  data = ["foo", "bar"]
  

  Modules using JSV.defschema/1 will automatically export the new function as well as the old one, with a deprecation warning.

• That defschema macro now supports passing the properties as a list directly.
  So instead of this:

  defmodule MyApp.UserSchema do
    use JSV.Schema
  
    defschema %{
      type: :object,
      properties: %{
        name: %{type: :string},
        age: %{type: :integer, default: 0}
      }
    }
  end
  

  You can do this:

  defmodule MyApp.UserSchema do
    use JSV.Schema
  
    defschema name: %{type: :string},
              age: %{type: :integer, default: 0}
  end
  

  And because use JSV.Schema imports the new schema definition helpers, it can be as short as this:

  defmodule MyApp.UserSchema do
    use JSV.Schema
  
    defschema name: string(),
              age: integer(default: 0)
  end
  

• Finally, I’ve added the defschema/3 macro that works like defschema/1 but also defines a module:

  defmodule MyApp.Schemas do
    use JSV.Schema
  
    defschema User, 
      name: string(),
      age: integer(default: 0)
  
    defschema Admin,
      """
      With a schema description and @moduledoc
      """,
      user: User,
      privileges: array_of(string())
  end
  

  I think it’s nice to have this when defining some responses schemas directly in controllers or message queue consumers, à la Pydantic.

And that’s it Thanks for reading!

[0.10.0] - 2025-07-10

Features

• Define and expect schema modules to export json_schema/0 instead of schema/0
• Allow to call defschema with a list of properties
• Added the defschema/3 macro to define schemas as submodules

Bug Fixes

• Ensure defschema with keyword syntax supports module-based properties

Hello,

I’ve just released a new version for JSV (a JSON Schema Validation library).

While working on support for OpenAPI 3.1 I needed to be able to use generic JSON documents as a repository for schemas. For instance, in an OpenAPI specification JSON document, the “API spec” itself is not a JSON schema, but it contains schemas. There is no need to transform the whole document in a schema that would validate nothing (as there are no schema keywords like type or properties at the root level).

So it’s now possible to have a document, and only build one or several parts of it into the “validation root” that JSV uses for validation. This is not documented for now as I am still waiting to see if it covers all my needs. But to implement that I had to make some breaking changes, and I’m releasing those now, better sooner than later.

Breaking changes

For regular usage of the library this should not impact your workflow.

• [breaking] Defschema does not automatically define $id anymore
• [breaking] Error normalizer will now sort error by instanceLocation
• [breaking] Changed caster tag of defschema to 0
• [breaking] Changed order of arguments for Normalizer.normalize/3

Full Changelog.

Incoming changes

In a next release I also want to sunset the composition API for schemas. This API looks like this:

alias JSV.Schema

%Schema{}
|> Schema.object()
|> Schema.properties(%{
  age: Schema.integer(description: "The age")
  my_prop: name_schema
})
|> Schema.required([...])

While this looks nice, I feel it’s pretty useless. If you already know what’s going to be in the schema you can just declare it that way:

%Schema{
  type: :object,
  properties: %{
    age: Schema.integer(description: "The age")
    my_prop: name_schema
  },
  required: [...]
}

This does not prevent you to have dynamic values like the name_schema variable.

The problem with that API is that the functions accept an optional first argument, the base to merge onto. For instance with Schema.integer/1 above,instead of piping in, I just passed the base directly and it’s explicit.

But if you want to define a schema with string_to_atom_enum/2 and a description for instance, you need to do this:

%{
  properties: %{
    my_enum:
      JSV.Schema.string_to_atom_enum(
        %{
          description: "Some description"
        },
        [:aaa, :bbb, :ccc]
      )
  }
}

Whereas what you expect to see is something like that:

%{
  properties: %{
    my_enum: JSV.Schema.string_to_atom_enum(
      [:aaa, :bbb, :ccc],
      description: "Some description"
    )
  }
}

That is, the first argument corresponds to the function name (in this case an enumeration of atoms), and maybe some optional overrides.

So I plan to move all those functions into a “composition API” module, and maybe deprecate them. JSON schemas are data and not code, it should always be possible to know the keys we want in there from the beginning. For the rare cases where we could not, I’ll keep the merge function anyway.

And then replace those functions with new helpers that take overrides as the last argument.

But I’d like to have you opinion on this

Thank you

Hello,

I just released a new version for JSV

As mentioned in the previous version thread I wanted to change the functional API used to define schemas, mostly because it was kind of useless for that type of data.

Basically I have deprecated building schemas like this…

object() 
|> properties(foo: integer()) 
|> required(:foo)

…because there were no additional value from that syntax, and only a performance cost.

New helpers are available, there is less of them for now, and they are not composable (not pipeable) but they are more readable given the extra attributes (like `description “foo…”) are always the last argument.

I believe this will lead to simpler code given schemas are static data 99% of the time.

More information in the docs API Changes in JSV 0.9 — jsv v0.16.0

I’m also happy to see that the Vaux library uses JSV for attribute validation in HTML components, which is quite cool!

[0.9.0] - 2025-07-05

Features

• Provide a schema representing normalized validation errors
• Deprecated the schema composition API in favor of presets

Bug Fixes

• Emit a build error with empty oneOf/allOf/anyOf
• Reset errors when using a detached validator
• Ensure casts are applied after all validations
• Revert default normalized error to atoms

Version 0.4.0 has been released.

• It is now possible to define a struct based on a schema.

  defmodule MyApp.UserSchema do
    require JSV
  
    JSV.defschema(%{
      type: :object,
      properties: %{
        name: %{type: :string, default: ""},
        age: %{type: :integer, default: 0}
      }
    })
  end    
  

• It is now possible to use a module name to reference a subschema:

  defmodule MyApp.RoleSchema do
    def schema do
      %{enum: ["admin","author","subscriber"]}
    end
  end
  
  schema = %{
    properties: %{
      # Reference a module that uses defschema/1
      user: MyApp.UserSchema,
      # Reference a module that simply exports schema/1
      role: MyApp.RoleSchema
    }
  }
  
  root = JSV.build!(schema)
  
  JSV.validate(%{"user" => %{"name" => "Alice"}, "role" => "admin"}, root)
  # returns:
  {:ok, %{"user" => %MyApp.UserSchema{age: 0, name: "Alice"}, "role" => "admin"}}
  

Hey !

I made some breaking changes in version 0.6 to support the new cast functions feature.

Cast functions allow to define the jsv-cast function in a JSON schema to call a custom function on validation and return a different value that what is in the raw data.

For instance with a module defined like this:

defmodule MyApp.Schemas.Cast do
  import JSV

  defcast to_uppercase(data) do
    {:ok, String.upcase(data)}
  end
end

And the following schema:

%{
  type: :string,
  "jsv-cast": ["Elixir.MyApp.Schemas.Cast", "to_uppercase"]
}

The cast function is automatically called upon validation:

root = JSV.build!(schema)
{:ok, "HELLO"} = JSV.validate("hello", root)

I made a defcast macro because I do not want the schema to contain a [module, function] value directly, for obvious security reasons. Besides that, it’s just a normal function that could be enabled this way:

defcast "to_uppercase", :my_secret_function

defp my_secret_function(data) do
  {:ok, String.upcase(data)}
end

This new feature includes some breaking change because the capability of defining a struct along with a schema is now based on cast functions as well.

More changes from the full changelog

• Resolvers do not need to normalize schemas anymore
• Added support to override existing vocabularies
• Schema definition helpers do not enforce a Schema struct anymore
• Provide a generic JSON normalizer for data and schemas
• Allow resolvers to mark schemas as normalized

I think JSV is now ready to support OpenAI specifications tooling but I’m hesitating going for it. So many things to do.

Anyway, have a wonderful week!