honk

An AT Protocol Lexicon validator for Gleam.

While I’ve tried to be as thorough as possible checking the validators against various atproto validation libraries, this may contain bugs. Please report any issues you find.

Installation

gleam add honk@1

Quick Start

Validate a Lexicon Schema

import honk
import gleam/json

pub fn main() {
  let lexicon = json.object([
    #("lexicon", json.int(1)),
    #("id", json.string("xyz.statusphere.status")),
    #("defs", json.object([
      #("main", json.object([
        #("type", json.string("record")),
        #("key", json.string("tid")),
        #("record", json.object([
          #("type", json.string("object")),
          #("required", json.preprocessed_array([
            json.string("status"),
            json.string("createdAt"),
          ])),
          #("properties", json.object([
            #("status", json.object([
              #("type", json.string("string")),
              #("minLength", json.int(1)),
              #("maxGraphemes", json.int(1)),
              #("maxLength", json.int(32)),
            ])),
            #("createdAt", json.object([
              #("type", json.string("string")),
              #("format", json.string("datetime")),
            ])),
          ])),
        ])),
      ])),
    ])),
  ])

  case honk.validate([lexicon]) {
    Ok(_) -> io.println("✓ Lexicon is valid")
    Error(err) -> io.println("✗ Validation failed: " <> err.message)
  }
}

Validate Record Data

import honk
import gleam/json

pub fn validate_status() {
  let lexicons = [my_lexicon] // Your lexicon definitions
  let record_data = json.object([
    #("status", json.string("👍")),
    #("createdAt", json.string("2025-01-15T12:00:00Z")),
  ])

  case honk.validate_record(lexicons, "xyz.statusphere.status", record_data) {
    Ok(_) -> io.println("✓ Record is valid")
    Error(err) -> io.println("✗ Invalid: " <> err.message)
  }
}

Features

• Type Validators: string, integer, boolean, bytes, blob, cid-link, null, object, array, union, ref, record, query, procedure, subscription, token, unknown
• String Format Validators: datetime (RFC3339), uri, at-uri, did, handle, at-identifier, nsid, cid, language, tid, record-key
• Constraint Validation: length limits, ranges, enums, required fields
• Reference Resolution: local (#def), global (nsid#def), and cross-lexicon references
• Detailed Error Messages: validation errors with path information

CLI Usage

Validate lexicon files from the command line:

# Validate a single file
gleam run -m honk check ./lexicons/xyz/statusphere/status.json

# Validate all .json files in a directory
gleam run -m honk check ./lexicons/

# Show help
gleam run -m honk help

When validating a directory, all lexicons are loaded together to resolve cross-lexicon references

Testing

gleam test

Documentation

Further documentation can be found at https://hexdocs.pm/honk.

Development

gleam run   # Run the project
gleam test  # Run the tests
gleam build # Build the project

License

Apache 2.0