A Clojure library for describing, validating and coercing user input.

This library is still in very early development.

[listora/constraint "0.0.6"]

Constraint draws upon ideas from Prismatic's Schema library and the core.typed static type system. It's designed to manage user input, particularly in the case of a public-facing web service. For this reason, specific emphasis is placed on providing readable and useful user-facing error messages.

Unlike Schema and core.typed, Constraint does not concern itself with the data passed between internal functions. Constraint will not help you find bugs in your application, but may help your users understand what they're doing wrong.

Constraint uses a concise but expressive syntax for describing data. This definition is known as a constraint.

(def Product
  {:id       UUID
   :name     String
   :price    (I BigDecimal (minimum 0))
   :stock    (I Integer (minimum 0))
   :tags     #{(& Keyword)}
   (? :size) [Number Number Number]})

The syntax borrows elements from core.typed and Clojure destructuring syntax. A full definition of the syntax can be found in the wiki.

• Wiki

If you just want to know whether a constraint is valid or not, there is the valid? function:

(valid? String "foo")  ;; => true

But more often it's useful to get a list of error messages:

(validate String 1)
=> ({:message  "data type does not match definition"
     :error    :invalid-type
     :expected java.lang.String
     :found    java.lang.Long})

Each error message will always contain an :error key that describes the type of error.

Constraints can be serialized into JSON Schema for documentation purposes.

For example:

(json-schema {:name String, (? :age) Integer})

Will produce:

{
    "$schema"   "https://json-schema.org/draft-04/schema#",
    "type"      "object",
    "required": ["name"],
    "additionalProperties": false,
    "properties": {
        "name": {"type": "string"},
        "age":  {"type": "integer"}
    }
}

Additional documentation can be included via the constraint.core/desc function:

(json-schema {:name (desc String "A person's full name")})

Produces:

{
    "$schema"   "https://json-schema.org/draft-04/schema#",
    "type"      "object",
    "required": ["name"],
    "additionalProperties": false,
    "properties": {
        "name": {"type": "string", "doc": "A person's full name"},
    }
}

Because Constraint can validate more complex structures than JSON Schema can, the resulting JSON Schema may not include all possible validations, especially if custom validation types are used.

Copyright © 2014 Listora

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.