{"id":21030970,"url":"https://github.com/azutoolkit/schema","last_synced_at":"2025-05-15T11:33:00.881Z","repository":{"id":39672687,"uuid":"149523731","full_name":"azutoolkit/schema","owner":"azutoolkit","description":"Schemas come to solve a simple problem. Sometimes we would like to have type-safe guarantee params when parsing HTTP parameters or Hash(String, String) for a request moreover; Schemas is to resolve precisely this problem with the added benefit of performing business rules validation to have the params adhere to a \"business schema.\"","archived":false,"fork":false,"pushed_at":"2023-06-10T14:22:22.000Z","size":143,"stargazers_count":33,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-03T08:51:22.462Z","etag":null,"topics":["http-params","json","parameters","parsing","predicates","schema-validations","typesafe","validation"],"latest_commit_sha":null,"homepage":"","language":"Crystal","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/azutoolkit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-09-19T23:26:39.000Z","updated_at":"2024-05-31T15:41:12.000Z","dependencies_parsed_at":"2024-11-19T12:33:27.776Z","dependency_job_id":"b63ffc0c-bb86-441e-8a34-52a717ce0c05","html_url":"https://github.com/azutoolkit/schema","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azutoolkit%2Fschema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azutoolkit%2Fschema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azutoolkit%2Fschema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azutoolkit%2Fschema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/azutoolkit","download_url":"https://codeload.github.com/azutoolkit/schema/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254330953,"owners_count":22053083,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["http-params","json","parameters","parsing","predicates","schema-validations","typesafe","validation"],"created_at":"2024-11-19T12:22:43.446Z","updated_at":"2025-05-15T11:32:59.391Z","avatar_url":"https://github.com/azutoolkit.png","language":"Crystal","readme":"\u003cdiv style=\"text-align:center\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/azutoolkit/schema/master/schema2.png\" /\u003e\u003c/div\u003e\n\n# Schema\n\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/bcab4bfe3c9c4c45a832fd724aa1ffea)](https://app.codacy.com/manual/eliasjpr/schema?utm_source=github.com\u0026utm_medium=referral\u0026utm_content=eliasjpr/schema\u0026utm_campaign=Badge_Grade_Dashboard)\n\n![Crystal CI](https://github.com/eliasjpr/schema/workflows/Crystal%20CI/badge.svg)\n\nSchemas come to solve a simple problem. Sometimes we would like to have type-safe guarantee parameters when parsing HTTP requests or Hash(String, String) for a request. Schema shard resolve precisely this problem with the added benefit of enabling self validating schemas that can be applied to any object, requiring little to no boilerplate code making you more productive from the moment you use this shard.\n\nSelf validating Schemas are beneficial, and in my opinion, ideal, for when defining API Requests, Web Forms, JSON.  Schema-Validation Takes a different approach and focuses a lot on explicitness, clarity, and precision of validation logic. It is designed to work with any data input, whether it’s a simple hash, an array or a complex object with deeply nested data.\n\nEach validation is encapsulated by a simple, stateless predicate that receives some input and returns either true or false. Those predicates are encapsulated by rules which can be composed together using predicate logic, meaning you can use the familiar logic operators to build up a validation schema.\n\n## Installation\n\nAdd this to your application's `shard.yml`:\n\n```yaml\ndependencies:\n  schema:\n    github: azutoolkit/schema\n```\n\n## Usage\n\n```crystal\nrequire \"schema\"\n```\n\n### Defining Self Validated Schemas\n\nSchemas are defined as value objects, meaning structs, which are NOT mutable,\nmaking them ideal to pass schema objects as arguments to constructors.\n\n```crystal\nclass Example\n  include Schema::Definition\n  include Schema::Validation\n\n  property email : String\n  property name : String\n  property age : Int32\n  property alive : Bool\n  property childrens : Array(String)\n  property childrens_ages : Array(Int32)\n  property last_name : String\n\n  use EmailValidator, UniqueRecordValidator\n  validate :email, match: /\\w+@\\w+\\.\\w{2,3}/, message: \"Email must be valid!\"\n  validate :name, size: (1..20)\n  validate :age, gte: 18, lte: 25, message: \"Age must be 18 and 25 years old\"\n  validate :alive, eq: true\n  validate :last_name, presence: true, message: \"Last name is invalid\"\n\n  predicates do\n    def some?(value : String, some) : Bool\n      (!value.nil? \u0026\u0026 value != \"\") \u0026\u0026 !some.nil?\n    end\n\n    def if?(value : Array(Int32), bool : Bool) : Bool\n      !bool\n    end\n  end\n\n  def initialize(@email, @name, @age, @alive, @childrens, @childrens_ages, @last_name)\n  end\nend\n```\n\n### Schema class methods\n\n```crystal\nExample.from_json\nExample.from_urlencoded(\"\u0026foo=bar\")\n# Any object that responds to `.each`, `#[]?`, `#[]`, `#fetch_all?`\nExample.new(params)\n```\n\n### Schema instance methods\n\n```crystal\nvalid?    - Bool\nvalidate! - True or Raise ValidationError\nerrors    - Errors(T, S)\n```\n\n### Example parsing HTTP Params (With nested params)\n\nBelow find a list of the supported params parsing structure and it's corresponding representation in Query String or `application/x-www-form-urlencoded` form data. \n\n```crystal\nhttp_params = HTTP::Params.build do |p|\n  p.add(\"string\", \"string_value\")\n  p.add(\"optional_string\", \"optional_string_value\")\n  p.add(\"string_with_default\", \"string_with_default_value\")\n  p.add(\"int\", \"1\")\n  p.add(\"optional_int\", \"2\")\n  p.add(\"int_with_default\", \"3\")\n  p.add(\"enum\", \"Foo\")\n  p.add(\"optional_enum\", \"Bar\")\n  p.add(\"enum_with_default\", \"Baz\")\n  p.add(\"array[]\", \"foo\")\n  p.add(\"array[]\", \"bar\")\n  p.add(\"array[]\", \"baz\")\n  p.add(\"optional_array[]\", \"foo\")\n  p.add(\"optional_array[]\", \"bar\")\n  p.add(\"array_with_default[]\", \"foo\")\n  p.add(\"hash[foo]\", \"1\")\n  p.add(\"hash[bar]\", \"2\")\n  p.add(\"optional_hash[foo][]\", \"3\")\n  p.add(\"optional_hash[foo][]\", \"4\")\n  p.add(\"optional_hash[bar][]\", \"5\")\n  p.add(\"hash_with_default[foo]\", \"5\")\n  p.add(\"tuple[]\", \"foo\")\n  p.add(\"tuple[]\", \"2\")\n  p.add(\"tuple[]\", \"3.5\")\n  p.add(\"boolean\", \"1\")\n  p.add(\"optional_boolean\", \"false\")\n  p.add(\"boolean_with_default\", \"true\")\n  p.add(\"nested[foo]\", \"1\")\n  p.add(\"nested[bar]\", \"3\")\n  p.add(\"nested[baz][]\", \"foo\")\n  p.add(\"nested[baz][]\", \"bar\")\nend\n```\n\n```crystal\nparams = HTTP::Params.parse(\"email=test%40example.com\u0026name=john\u0026age=24\u0026alive=true\u0026childrens%5B%5D=Child1%2CChild2\u0026childrens_ages%5B%5D=12\u0026childrens_ages%5B%5D=18\u0026address%5Bcity%5D=NY\u0026address%5Bstreet%5D=Sleepy+Hollow\u0026address%5Bzip%5D=12345\u0026address%5Blocation%5D%5Blongitude%5D=41.085651\u0026address%5Blocation%5D%5Blatitude%5D=-73.858467\u0026address%5Blocation%5D%5Buseful%5D=true\")\n\n# HTTP::Params responds to `#[]`, `#[]?`, `#fetch_all?` and `.each`\nsubject = ExampleController.new(params)\n```\n\nAccessing the generated schemas:\n\n```crystal\nuser      = subject.user     - Example\naddress   = user.address     - Example::Address\nlocation  = address.location - Example::Address::Location\n```\n\n## Example parsing from JSON\n\n```crystal\njson = %({ \"user\": {\n      \"email\": \"fake@example.com\",\n      \"name\": \"Fake name\",\n      \"age\": 25,\n      \"alive\": true,\n      \"childrens\": [\"Child 1\", \"Child 2\"],\n      \"childrens_ages\": [9, 12]\n    }})\n\nuser = Example.from_json(json, \"user\")\n```\n## Validations\n\nYou can also perform validations for existing objects without the use of Schemas.\n\n```crystal\nclass User \u003c Model\n  include Schema::Validation\n\n  property email : String\n  property name : String\n  property age : Int32\n  property alive : Bool\n  property childrens : Array(String)\n  property childrens_ages : Array(Int32)\n\n  # To use a custom validator. UniqueRecordValidator will be initialized with an `User` instance\n  use UniqueRecordValidator\n\n  # Use the `custom` class name predicate as follow\n  validate email, match: /\\w+@\\w+\\.\\w{2,3}/, message: \"Email must be valid!\", unique_record: true\n  validate name, size: (1..20)\n  validate age, gte: 18, lte: 25, message: \"Must be 24 and 30 years old\"\n  validate alive, eq: true\n\n  def initialize(@email, @name, @age, @alive, @childrens, @childrens_ages)\n  end\nend\n```\n\n### Custom Validations\n\nSimply create a class `{Name}Validator` with the following signature:\n\n```crystal\nclass EmailValidator \u003c Schema::Validator\n  getter :record, :field, :message\n\n  def initialize(@record : UserModel)\n    @field = :email\n    @message = \"Email must be valid!\"\n  end\n\n  def valid? : Array(Schema::Error)\n    [] of Schema::Error\n  end\nend\n\nclass UniqueRecordValidator \u003c Schema::Validator\n  getter :record, :field, :message\n\n  def initialize(@record : UserModel)\n    @field = :email\n    @message = \"Record must be unique!\"\n  end\n\n  def valid? : Array(Schema::Error)\n    [] of Schema::Error\n  end\nend\n```\n\n### Defining Predicates\n\nYou can define your custom predicates by simply creating a custom validator or creating methods in the `Schema::Predicates` module ending with `?` and it should return a `boolean`. For example:\n\n```crystal\nclass User \u003c Model\n  property email : String\n  property name : String\n  property age : Int32\n  property alive : Bool\n  property childrens : Array(String)\n  property childrens_ages : Array(Int32)\n\n  ...\n\n  # Uses a `presense` predicate\n  validate password : String, presence: true\n\n  # Use the `predicates` macro to define predicate methods\n  predicates do\n    # Presence Predicate Definition\n    def presence?(password : String, _other : String) : Bool\n      !value.nil?\n    end\n  end\n\n  def initialize(@email, @name, @age, @alive, @childrens, @childrens_ages)\n  end\nend\n```\n\n### Differences: Custom Validator vs Predicates\n\nThe differences between a custom validator and a method predicate are:\n\n**Custom Validators**\n-   Must be inherited from `Schema::Validator` abstract\n-   Receives an instance of the object as a `record` instance var.\n-   Must have a `:field` and `:message` defined.\n-   Must implement a `def valid? : Array(Schema::Error)` method.\n\n**Predicates**\n-   Assertions of the property value against an expected value.\n-   Predicates are light weight boolean methods.\n-   Predicates methods must be defined as `def {predicate}?(property_value, expected_value) : Bool` .\n\n### Built in Predicates\n\nThese are the current available predicates.\n\n```crystal\ngte   - Greater Than or Equal To\nlte   - Less Than or Equal To\ngt    - Greater Than\nlt    - Less Than\nsize  - Size\nin    - Inclusion\nregex - Regular Expression\neq    - Equal\n```\n\n\u003e **CONTRIBUTE** - Add more predicates to this shards by contributing a Pull Request. \n\nAdditional params\n\n```crystal\nmessage - Error message to display\nnilable - Allow nil, true or false\n```\n\n## Contributing\n\n1.  Fork it (\u003chttps://github.com/your-github-user/schemas/fork\u003e)\n2.  Create your feature branch (`git checkout -b my-new-feature`)\n3.  Commit your changes (`git commit -am 'Add some feature'`)\n4.  Push to the branch (`git push origin my-new-feature`)\n5.  Create a new Pull Request\n\n## Contributors\n\n-   [@eliasjpr](https://github.com/eliasjpr) Elias J. Perez - creator, maintainer\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazutoolkit%2Fschema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fazutoolkit%2Fschema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazutoolkit%2Fschema/lists"}