Argot

Argot (/är′gō/) noun

A characteristic language of a particular group (as among thieves).

Argot is a simple gem for quickly and flexibly building minimal, validatable YAML schemas. Its original inspiration came from this blog post by @burke.

Argot aims to be:

Simple (i.e., non-bureuacratic)
Flexible
Easy to Understand and Extend

Argot aims to avoid:

Arcane syntax
Having many layers of abstraction between the schema you write and the document you validate

Example Schema

%TAG ! tag:argot.packfiles.io,2024:
---

# "version" is optional. When supplied, it must be the literal string "latest" or match the regular expression ^\d+.\d+.\d+$
# The !one tag describes a sequence of acceptable validation rules for a given key
!o version: !one
- !l "latest"
- !x '^\d+.\d+.\d+$'

# "farmer_name" is required, and its value must match the regular expression ^Farmer [a-zA-Z]+$
!r farmer_name: !x '^Farmer [a-zA-Z]+$'

# "farmer_level" must be an Integer type
!o farmer_level: !t Integer

# The !x tag can also be used to describe validations that are applied 
# to any keys in a mapping whose name matches a regular expression
!o meats:
  !x 'beef_from_.*':
    !r grade: !one
      - !l "A"
      - !l "B"
      - !l "C"
      - !l "F"

# When a parent key is marked as optional, validation rules will be applied to its children only
# when that parent key is present in the document. In this case, the absence of the required 
# pasture_uuid key will only fail validation if its parent goat_zone key is present.
!o farm:
  !o goat_zone:
    !r pasture_uuid: !x '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
    !o goats_count: !t Integer

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add argot

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install argot

Usage

First, register an Argot schema:

test_schema = File.read("./test/fixtures/schemas/01.yml")
Argot::Schema.register(:test_schema, test_schema)

Then, validate some YAML files:

rules = Argot::Schema.for(:test_schema)

passing_document = File.read("./test/fixtures/documents/01-pass.yml")
failing_document = File.read("./test/fixtures/documents/01-fail.yml")


validator = Argot::Validator.parse_and_validate(rules, failing_document)
validator.errors? # true
validator.safe_load # nil

validator = Argot::Validator.parse_and_validate(rules, passing_document)
validator.errors? # false
validator.safe_load # parsed document Hash

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/chtzvt/argot.

License

The gem is available as open source under the terms of the MIT License.

Made with ❤️ by Packfiles 📦

argot