Kwalify User's Guide (for Ruby)

makoto kuwata <kwa(at)kuwata-lab.com>
last update: $Date$

Preface

Kwalify^(*1) is a parser, schema validator, and data binding tool for YAML and JSON. Kwalify enables you to handle YAML and JSON more easily and strictly.

Topics:

Schema validation for YAML and JSON
Class definition generation for Ruby, PHP, and Java
Data binding
Preceding alias

(*1): Pronounce as 'Qualify'.

Preface
- Table of Contents
Schema Definition
Tips
How to in Ruby
Actions
- Class Definition Generation
  - Ruby Class Definition
  - Java Class Definition
References
- Usage in Command-Line

Schema Definition

This section describes how to define schema definition of YAML.

Sequence

schema01.yaml : sequence of string

type:   seq
sequence:
  - type:   str

document01a.yaml : valid document example

- foo
- bar
- baz

validate

$ kwalify -lf schema01.yaml document01a.yaml
document01a.yaml#0: valid.

document01b.yaml : invalid document example

- foo
- 123
- baz

validate

$ kwalify -lf schema01.yaml document01b.yaml
document01b.yaml#0: INVALID
  - (line 2) [/1] '123': not a string.

Default 'type:' is str so you can omit 'type: str'.

Mapping

schema02.yaml : mapping of scalar

type:       map
mapping:
 "name":
    type:      str
    required:  yes
 "email":
    type:      str
    pattern:   /@/
 "age":
    type:      int
 "birth":
    type:      date

document02a.yaml : valid document example

name:   foo
email:  foo@mail.com
age:    20
birth:  1985-01-01

validate

$ kwalify -lf schema02.yaml document02a.yaml
document02a.yaml#0: valid.

document02b.yaml : invalid document example

name:   foo
email:  foo(at)mail.com
age:    twenty
birth:  Jun 01, 1985

validate

$ kwalify -lf schema02.yaml document02b.yaml
document02b.yaml#0: INVALID
  - (line 2) [/email] 'foo(at)mail.com': not matched to pattern /@/.
  - (line 3) [/age] 'twenty': not a integer.
  - (line 4) [/birth] 'Jun 01, 1985': not a date.

Sequence of Mapping

schema03.yaml : sequence of mapping

type:      seq
sequence:
  - type:      map
    mapping:
     "name":
        type:      str
        required:  true
     "email":
        type:      str

document03a.yaml : valid document example

- name:   foo
  email:  foo@mail.com
- name:   bar
  email:  bar@mail.net
- name:   baz
  email:  baz@mail.org

validate

$ kwalify -lf schema03.yaml document03a.yaml
document03a.yaml#0: valid.

document03b.yaml : invalid document example

- name:   foo
  email:  foo@mail.com
- naem:   bar
  email:  bar@mail.net
- name:   baz
  mail:   baz@mail.org

validate

$ kwalify -lf schema03.yaml document03b.yaml
document03b.yaml#0: INVALID
  - (line 3) [/1] key 'name:' is required.
  - (line 3) [/1/naem] key 'naem:' is undefined.
  - (line 6) [/2/mail] key 'mail:' is undefined.

Mapping of Sequence

schema04.yaml : mapping of sequence of mapping

type:      map
mapping:
 "company":
    type:      str
    required:  yes
 "email":
    type:      str
 "employees":
    type:      seq
    sequence:
      - type:    map
        mapping:
         "code":
            type:      int
            required:  yes
         "name":
            type:      str
            required:  yes
         "email":
            type:      str

document04a.yaml : valid document example

company:    Kuwata lab.
email:      webmaster@kuwata-lab.com
employees:
  - code:   101
    name:   foo
    email:  foo@kuwata-lab.com
  - code:   102
    name:   bar
    email:  bar@kuwata-lab.com

validate

$ kwalify -lf schema04.yaml document04a.yaml
document04a.yaml#0: valid.

document04b.yaml : invalid document example

company:    Kuwata Lab.
email:      webmaster@kuwata-lab.com
employees:
  - code:   A101
    name:   foo
    email:  foo@kuwata-lab.com
  - code:   102
    name:   bar
    mail:   bar@kuwata-lab.com

validate

$ kwalify -lf schema04.yaml document04b.yaml
document04b.yaml#0: INVALID
  - (line 4) [/employees/0/code] 'A101': not a integer.
  - (line 9) [/employees/1/mail] key 'mail:' is undefined.

Rule and Constraint

type:, required:, length, ... are called constraint and set of constraints are called rule.

Rule contains 'type:' constraint. If 'type:' is omitted, 'type: str' is used as default.
'sequence:' constraint takes a sequence of rule (the sequence can contain only a rule).
'mapping:' constraint takes a mapping which values are rules.

constraints and rules of schema definition.

The following is a list of constraints.

required:

Value is required when true (default is false). This is similar to not-null constraint in RDBMS.

enum:

List of available values.

pattern:

Specifies regular expression pattern of value.

type:

Type of value. The followings are available:

str
int
float
number (== int or float)
text (== str or number)
bool
date
time
timestamp
seq
map
scalar (all but seq and map)
any (means any data)

range:

Range of value between max/max-ex and min/min-ex.

'max' means 'max-inclusive'.
'min' means 'min-inclusive'.
'max-ex' means 'max-exclusive'.
'min-ex' means 'min-exclusive'.

Type seq, map, bool and any are not available with range:.

length:

Range of length of value between max/max-ex and min/min-ex. Only type str and text are available with length:.

assert:

String which represents validation expression. String should contain variable name val which repsents value. (This is an experimental function and not supported in Kwartz-java).

unique:

Value is unique for mapping or sequence. This is similar to unique constraint of RDBMS. See the next subsection for detail.

name:

Name of schema.

desc:

Description. This is not used for validation.

class:

Class name. This is for data-binding and is available only with type 'map'. This is also used in 'genclass' action.

default:

Default value. This is only for 'genclass' action, and have no effect to validation and parsing. Default value should be scalar and it is not available if type: is map or seq, and also not available when required: is true.

schema05.yaml : rule examples

type:      seq
sequence:
  -
    type:      map
    mapping:
     "name":
        type:       str
        required:   yes
     "email":
        type:       str
        required:   yes
        pattern:    /@/
     "password":
        type:       text
        length:     { max: 16, min: 8 }
     "age":
        type:       int
        range:      { max: 30, min: 18 }
        # or assert: 18 <= val && val <= 30
     "blood":
        type:       str
        enum:       [A, B, O, AB]
     "birth":
        type:       date
     "memo":
        type:       any
     "deleted":
        type:       bool
        default:    false

document05a.yaml : valid document example

- name:     foo
  email:    foo@mail.com
  password: xxx123456
  age:      20
  blood:    A
  birth:    1985-01-01
- name:     bar
  email:    bar@mail.net
  age:      25
  blood:    AB
  birth:    1980-01-01

validate

$ kwalify -lf schema05.yaml document05a.yaml
document05a.yaml#0: valid.

document05b.yaml : invalid document example

- name:     foo
  email:    foo(at)mail.com
  password: xxx123
  age:      twenty
  blood:    a
  birth:    1985-01-01
- given-name:  bar
  family-name: Bar
  email:    bar@mail.net
  age:      15
  blood:    AB
  birth:    1980/01/01

validate

$ kwalify -lf schema05.yaml document05b.yaml
document05b.yaml#0: INVALID
  - (line 2) [/0/email] 'foo(at)mail.com': not matched to pattern /@/.
  - (line 3) [/0/password] 'xxx123': too short (length 6 < min 8).
  - (line 4) [/0/age] 'twenty': not a integer.
  - (line 5) [/0/blood] 'a': invalid blood value.
  - (line 7) [/1] key 'name:' is required.
  - (line 7) [/1/given-name] key 'given-name:' is undefined.
  - (line 8) [/1/family-name] key 'family-name:' is undefined.
  - (line 10) [/1/age] '15': too small (< min 18).
  - (line 12) [/1/birth] '1980/01/01': not a date.

Unique constraint

'unique:' constraint is available with elements of sequence or mapping. This is equivalent to unique constraint of RDBMS.

Type of rule which has 'unique:' entry must be scalar (str, int, float, ...).
Type of parent rule must be sequence or mapping.

schema06.yaml : unique constraint entry with mapping and sequence

type: seq
sequence:
  - type:     map
    required: yes
    mapping:
     "name":   { type: str, required: yes, unique: yes }
     "email":  { type: str }
     "groups":
        type:     seq
        sequence:
          - { type: str, unique: yes }

document06a.yaml : valid document example

- name:   foo
  email:  admin@mail.com
  groups:
    - users
    - foo
    - admin
- name:   bar
  email:  admin@mail.com
  groups:
    - users
    - admin
- name:   baz
  email:  baz@mail.com
  groups:
    - users

validate

$ kwalify -lf schema06.yaml document06a.yaml
document06a.yaml#0: valid.

document06b.yaml : invalid document example

- name:   foo
  email:  admin@mail.com
  groups:
    - foo
    - users
    - admin
    - foo
- name:   bar
  email:  admin@mail.com
  groups:
    - admin
    - users
- name:   bar
  email:  baz@mail.com
  groups:
    - users

validate

$ kwalify -lf schema06.yaml document06b.yaml
document06b.yaml#0: INVALID
  - (line 7) [/0/groups/3] 'foo': is already used at '/0/groups/0'.
  - (line 13) [/2/name] 'bar': is already used at '/1/name'.

Tips

JSON

JSON is a lightweight data-interchange format, especially useful for JavaScript. JSON can be considered as a subset of YAML. It means that YAML parser can parse JSON and Kwalify can validate JSON document.

schema12.json : an example schema definition written in JSON format

{ "type": "map",
  "required": true,
  "mapping": {
    "name":   { "type": "str", "required": true },
    "email":  { "type": "str" },
    "age":    { "type": "int" },
    "gender": { "type": "str", "enum": ["M", "F"] },
    "favorite": { "type": "seq",
                  "sequence": [ { "type": "str" } ]
                }
  }
}

document12a.json : valid JSON document example

{ "name": "Foo",
  "email": "foo@mail.com",
  "age": 20,
  "gender": "F",
  "favorite": [
     "football",
     "basketball",
     "baseball"
  ]
}

validate

$ kwalify -lf schema12.json document12a.json
document12a.json#0: valid.

document12b.json : invalid JSON document example

{
  "mail": "foo@mail.com",
  "age": twenty,
  "gender": "X",
  "favorite": [ 123, 456 ]
}

validate

$ kwalify -lf schema12.json document12b.json
document12b.json#0: INVALID
  - (line 1) [/] key 'name:' is required.
  - (line 2) [/mail] key 'mail:' is undefined.
  - (line 3) [/age] 'twenty': not a integer.
  - (line 4) [/gender] 'X': invalid gender value.
  - (line 5) [/favorite/0] '123': not a string.
  - (line 5) [/favorite/1] '456': not a string.

Anchor and Alias

You can share rules by YAML anchor and alias.

schema13.yaml : anchor example

type:   seq
sequence:
  - &employee
    type:      map
    mapping:
     "given-name": &name
        type:     str
        required: yes
     "family-name": *name
     "post":
        type: str
        enum: [exective, manager, clerk]
     "supervisor":  *employee

Anchor and alias is also available in YAML document.

document13a.yaml : valid document example

- &foo
  given-name:    foo
  family-name:   Foo
  post:          exective
- &bar
  given-name:    bar
  family-name:   Bar
  post:          manager
  supervisor:    *foo
- given-name:    baz
  family-name:   Baz
  post:          clerk
  supervisor:    *bar
- given-name:    zak
  family-name:   Zak
  post:          clerk
  supervisor:    *bar

validate

$ kwalify -lf schema13.yaml document13a.yaml
document13a.yaml#0: valid.

Default of Mapping

YAML allows user to specify default value of mapping.

For example, the following YAML document uses default value of mapping.

A: 10
B: 20
=: -1      # default value

This is equal to the following Ruby code.

map = ["A"=>10, "B"=>20]
map.default = -1
map

Kwalify allows user to specify default rule using default value of mapping. It is useful when key names are unknown.

schema14.yaml : default rule example

type: map
mapping:
  =:              # default rule
    type: number
    range: { max: 1, min: -1 }

document14a.yaml : valid document example

value1: 0
value2: 0.5
value3: -0.9

validate

$ kwalify -lf schema14.yaml document14a.yaml
document14a.yaml#0: valid.

document14b.yaml : invalid document example

value1: 0
value2: 1.1
value3: -2.0

validate

$ kwalify -lf schema14.yaml document14b.yaml
document14b.yaml#0: INVALID
  - (line 2) [/value2] '1.1': too large (> max 1).
  - (line 3) [/value3] '-2.0': too small (< min -1).

Merging Mappings

YAML allows user to merge mappings.

- &a1
  A: 10
  B: 20
- <<: *a1            # merge
  A: 15              # override
  C: 30              # add

This is equal to the following Ruby code.

a1 = {"A"=>10, "B"=>20}
tmp = {}
tmp.update(a1)       # merge
tmp["A"] = 15        # override
tmp["C"] = 30        # add

This feature allows Kwalify to merge rule entries.

schema15.yaml : merging rule entries example

type: map
mapping:
 "group":
    type: map
    mapping:
     "name": &name
        type: str
        required: yes
     "email": &email
        type: str
        pattern: /@/
        required: no
 "user":
    type: map
    mapping:
     "name":
        <<: *name             # merge
        length: { max: 16 }   # add
     "email":
        <<: *email            # merge
        required: yes         # override

document15a.yaml : valid document example

group:
  name: foo
  email: foo@mail.com
user:
  name: bar
  email: bar@mail.com

validate

$ kwalify -lf schema15.yaml document15a.yaml
document15a.yaml#0: valid.

document15b.yaml : invalid document example

group:
  name: foo
  email: foo@mail.com
user:
  name: toooooo-looooong-name

validate

$ kwalify -lf schema15.yaml document15b.yaml
document15b.yaml#0: INVALID
  - (line 5) [/user] key 'email:' is required.
  - (line 5) [/user/name] 'toooooo-looooong-name': too long (length 21 > max 16).

How to in Ruby

This section describes how to use Kwalify in Ruby.

Validation

require 'kwalify'
#require 'yaml'

## load schema data
schema = Kwalify::Yaml.load_file('schema.yaml')
## or
#schema = YAML.load_file('schema.yaml')

## create validator
validator = Kwalify::Validator.new(schema)

## load document
document = Kwalify::Yaml.load_file('document.yaml')
## or
#document = YAML.load_file('document.yaml')

## validate
errors = validator.validate(document)

## show errors
if errors && !errors.empty?
  for e in errors
    puts "[#{e.path}] #{e.message}"
  end
end

Parsing with Validation

From version 0.7, Kwalify supports parsing with validation.

require 'kwalify'
#require 'yaml'

## load schema data
schema = Kwalify::Yaml.load_file('schema.yaml')
## or
#schema = YAML.load_file('schema.yaml')

## create validator
validator = Kwalify::Validator.new(schema)

## create parser with validator
## (if validator is ommitted, no validation executed.)
parser = Kwalify:::Yaml::Parser.new(validator)

## parse document with validation
filename = 'document.yaml'
document = parser.parse_file(filename)
## or
#document = parser.parse(File.read(filename), filename)

## show errors if exist
errors = parser.errors()
if errors && !errors.empty?
  for e in errors
    puts "#{e.linenum}:#{e.column} [#{e.path}] #{e.message}"
  end
end

Meta Validation

Meta validator is a validator which validates schema definition. The schema definition is placed at 'kwalify/kwalify.schema.yaml'.

Kwalify also provides Kwalify::MetaValidator class which validates schema defition.

require 'kwalify'

## meta validator
metavalidator = Kwalify::MetaValidator.instance

## validate schema definition
parser = Kwalify::Yaml::Parser.new(metavalidator)
errors = parser.parse_file('schema.yaml')
for e in errors
  puts "#{e.linenum}:#{e.column} [#{e.path}] #{e.message}"
end if errors && !errors.empty?

Meta validation is also available with command-line option '-m'.

$ kwalify -m schema1.yaml schema2.yaml ...

Validator#validator_hook()

You can extend Kwalify::Validator and override Kwalify::Validator#validator_hook() method. This method is called by Kwalify::Validator#validate().

answers-schema.yaml : 'name:' is important.

type:      map
mapping:
 "answers":
    type:      seq
    sequence:
      - type:      map
        name:        Answer
        mapping:
         "name":   { type: str, required: yes }
         "answer": { type: str, required: yes,
                     enum: [good, not bad, bad] }
         "reason": { type: str }

answers-validator.rb : validate script for Ruby

#!/usr/bin/env ruby

require 'kwalify'

## validator class for answers
class AnswersValidator < Kwalify::Validator

   ## load schema definition
   @@schema = Kwalify::Yaml.load_file('answers-schema.yaml')
   ## or
   ##   require 'yaml'
   ##   @@schema = YAML.load_file('answers-schema.yaml')

   def initialize()
      super(@@schema)
   end

   ## hook method called by Validator#validate()
   def validate_hook(value, rule, path, errors)
      case rule.name
      when 'Answer'
         if value['answer'] == 'bad'
            reason = value['reason']
            if !reason || reason.empty?
               msg = "reason is required when answer is 'bad'."
               errors << Kwalify::ValidationError.new(msg, path)
            end
         end
      end
   end

end

## create validator
validator = AnswersValidator.new

## parse and validate YAML document
input = ARGF.read()
parser = Kwalify::Yaml::Parser.new(validator)
document = parser.parse(input)

## show errors
errors = parser.errors()
if !errors || errors.empty?
   puts "Valid."
else
   puts "*** INVALID!"
   for e in errors
      # e.class == Kwalify::ValidationError
      puts "#{e.linenum}:#{e.column} [#{e.path}] #{e.message}"
   end
end

document07a.yaml : valid document example

answers:
  - name:      Foo
    answer:    good
    reason:    I like this style.
  - name:      Bar
    answer:    not bad
  - name:      Baz
    answer:    bad
    reason:    I don't like this style.

validate

$ ruby answers-validator.rb document07a.yaml
Valid.

document07b.yaml : invalid document example

answers:
  - name:    Foo
    answer:  good
  - name:    Bar
    answer:  bad
  - name:    Baz
    answer:  not bad

validate

$ ruby answers-validator.rb document07b.yaml
*** INVALID!
4:3 [/answers/1] reason is required when answer is 'bad'.

You can validate some document by a Validator instance because Validator class and Validator#validate() method are stateless. If you use instance variables in custom validator_hook() method, it becomes to be stateful.

Preceding Alias

From version 0.7, Kwalify allows aliases to appear before corresponding anchors are now appeared. These aliases are called as 'preceding alias'.

howto3.yaml

- name: Foo
  parent: *bar        # preceding alias
- &bar
  name: Bar
  parent: *baz        # preceding alias
- &baz
  name: Baz
  parent: null

To enable preceding alias, set Kwalify::Yaml::Parser#preceding_alias to true.

howto3.rb

require 'kwalify'
parser = Kwalify::Yaml::Parser.new
parser.preceding_alias = true   # enable preceding alias
ydoc = parser.parse_file('howto3.yaml')
require 'pp'
pp ydoc

result

$ ruby howto3.rb
[{"name"=>"Foo",
  "parent"=>{"name"=>"Bar", "parent"=>{"name"=>"Baz", "parent"=>nil}}},
 {"name"=>"Bar", "parent"=>{"name"=>"Baz", "parent"=>nil}},
 {"name"=>"Baz", "parent"=>nil}]

Command-line option '-P' also enables preceding alias.

Preceding alias is very useful when document is complex.

Data Binding

From version 0.7, Kwalify supports data binding. * To enable data binding, set Kwlaify::Yaml::Parser#data_binding to true. * It is required to specify class name in schema definition. (Notice that 'class:' constraint is avaialbe only with rule which type is 'map'.) * Also instance methods '[]', '[]=', and 'keys?' must be defined in the classes. (Including Kwalify::Util::HashLike modules is easy way to define them.)

config.schema.yaml: schema definition file

type:  map
class: Config
mapping:
 "host": { type: str, required: true }
 "port": { type: int }
 "user": { type: str, required: true }
 "pass": { type: str, required: true }

config.yaml: data file

host:  localhost
port:  8080
user:  user1
pass:  password1

loadconfig.rb: ruby program

## class definition
require 'kwalify/util/hashlike'
class Config
  include Kwalify::Util::HashLike  # defines [], []=, and keys?
  attr_accessor :host, :posrt, :user, :pass
end
## create validator object
require 'kwalify'
schema = Kwalify::Yaml.load_file('config.schema.yaml')
validator = Kwalify::Validator.new(schema)
## parse configuration file with data binding
parser = Kwalify::Yaml::Parser.new(validator)
parser.data_binding = true    # enable data binding
config = parser.parse_file('config.yaml')
require 'pp'
pp config

result

$ ruby loadconfig.rb
#<Config:
 @host="localhost",
 @pass="password1",
 @port=8080,
 @user="user1">

Data binding is available even when data is more complex. Preceding alias is also available.

For example, the following data is complex because it uses anchor and alias (including preceding alias).

BABEL.data.yaml

teams:
  - &thechildren
    name:   The Children
    desc:   Level 7 ESPers
    chief:  *minamoto                  # preceding alias
    members:  [*kaoru, *aoi, *shiho]   # preceding aliases

members:
  - &minamoto
    name:   Kohichi Minamoto
    desc:   Scientist
    team:   *thechildren
  - &kaoru
    name:   Kaoru Akashi
    desc:   Psychokino
    team:   *thechildren
  - &aoi
    name:   Aoi Nogami
    desc:   Teleporter
    team:   *thechildren
  - &shiho
    name:   Shiho Sannomiya
    desc:   Psycometrer
    team:   *thechildren

Here is the schema definition. (Notice that 'class:' constraint is avaialbe only with rule which type is 'map'.)

BABEL.schema.yaml

type: map
required: yes
mapping:
 "teams":
    type: seq
    required: yes
    sequence:
      - &team
        type:  map
        required: yes
        class:  Team
        mapping:
         "name":  {type: str, required: yes, unique: yes}
         "desc":  {type: str}
         "chief":  *member       # preceding alias
         "members":
            type: seq
            sequence: [*member]  # preceding alias
 "members":
    type: seq
    required: yes
    sequence:
      - &member
        type:  map
        required: yes
        class:  Member
        mapping:
         "name":  {type: str, required: yes, unique: yes}
         "desc":  {type: str}
         "team":  *team

It is required to define class 'Team' and 'Member' for data-binding. Command-line option '-a genclass-ruby' will help you to generate class definitions from schema definition. Try 'kwalify -ha genclass-ruby' for more details about 'genclass-ruby' action.

$ kwalify -a genclass-ruby -P -f BABEL.schema.yaml \
    --hashlike --initialize=false --module=Babel
require 'kwalify/util/hashlike'

module Babel

  ## 
  class Team
    include Kwalify::Util::HashLike
    attr_accessor :name             # str
    attr_accessor :desc             # str
    attr_accessor :chief            # map
    attr_accessor :members          # seq
  end

  ## 
  class Member
    include Kwalify::Util::HashLike
    attr_accessor :name             # str
    attr_accessor :desc             # str
    attr_accessor :team             # map
  end

end
$ kwalify -a genclass-ruby -P -f BABEL.schema.yaml  \
    --hashlike --initialize=false --module=Babel > models.rb

Here is the ruby program.

loadbabel.rb

require 'kwalify'
require 'models'

## load schema definition
schema = Kwalify::Yaml.load_file('BABEL.schema.yaml',
                                 :untabify=>true,
                                 :preceding_alias=>true)

## add module name to 'class:'
Kwalify::Util.traverse_schema(schema) do |rulehash|
  if rulehash['class']
    rulehash['class'] = 'Babel::' + rulehash['class']
  end
end

## create validator
validator = Kwalify::Validator.new(schema)

## parse with data-binding
parser = Kwalify::Yaml::Parser.new(validator)
parser.preceding_alias = true
parser.data_binding = true
ydoc = parser.parse_file('BABEL.data.yaml', :untabify=>true)

## show document
require 'pp'
pp ydoc

result

$ ruby loadbabel.rb
{"teams"=>
  [#<Babel::Team:0x53e0f8
    @chief=
     #<Babel::Member:0x53d5e0
      @desc="Scientist",
      @name="Kohichi Minamoto",
      @team=#<Babel::Team:0x53e0f8 ...>>,
    @desc="Level 7 ESPers",
    @members=
     [#<Babel::Member:0x53d018
       @desc="Psychokino",
       @name="Kaoru Akashi",
       @team=#<Babel::Team:0x53e0f8 ...>>,
      #<Babel::Member:0x53ca50
       @desc="Teleporter",
       @name="Aoi Nogami",
       @team=#<Babel::Team:0x53e0f8 ...>>,
      #<Babel::Member:0x53c488
       @desc="Psycometrer",
       @name="Shiho Sannomiya",
       @team=#<Babel::Team:0x53e0f8 ...>>],
    @name="The Children">],
 "members"=>
  [#<Babel::Member:0x53d5e0
    @desc="Scientist",
    @name="Kohichi Minamoto",
    @team=
     #<Babel::Team:0x53e0f8
      @chief=#<Babel::Member:0x53d5e0 ...>,
      @desc="Level 7 ESPers",
      @members=
       [#<Babel::Member:0x53d018
         @desc="Psychokino",
         @name="Kaoru Akashi",
         @team=#<Babel::Team:0x53e0f8 ...>>,
        #<Babel::Member:0x53ca50
         @desc="Teleporter",
         @name="Aoi Nogami",
         @team=#<Babel::Team:0x53e0f8 ...>>,
        #<Babel::Member:0x53c488
         @desc="Psycometrer",
         @name="Shiho Sannomiya",
         @team=#<Babel::Team:0x53e0f8 ...>>],
      @name="The Children">>,
   #<Babel::Member:0x53d018
    @desc="Psychokino",
    @name="Kaoru Akashi",
    @team=
     #<Babel::Team:0x53e0f8
      @chief=
       #<Babel::Member:0x53d5e0
        @desc="Scientist",
        @name="Kohichi Minamoto",
        @team=#<Babel::Team:0x53e0f8 ...>>,
      @desc="Level 7 ESPers",
      @members=
       [#<Babel::Member:0x53d018 ...>,
        #<Babel::Member:0x53ca50
         @desc="Teleporter",
         @name="Aoi Nogami",
         @team=#<Babel::Team:0x53e0f8 ...>>,
        #<Babel::Member:0x53c488
         @desc="Psycometrer",
         @name="Shiho Sannomiya",
         @team=#<Babel::Team:0x53e0f8 ...>>],
      @name="The Children">>,
   #<Babel::Member:0x53ca50
    @desc="Teleporter",
    @name="Aoi Nogami",
    @team=
     #<Babel::Team:0x53e0f8
      @chief=
       #<Babel::Member:0x53d5e0
        @desc="Scientist",
        @name="Kohichi Minamoto",
        @team=#<Babel::Team:0x53e0f8 ...>>,
      @desc="Level 7 ESPers",
      @members=
       [#<Babel::Member:0x53d018
         @desc="Psychokino",
         @name="Kaoru Akashi",
         @team=#<Babel::Team:0x53e0f8 ...>>,
        #<Babel::Member:0x53ca50 ...>,
        #<Babel::Member:0x53c488
         @desc="Psycometrer",
         @name="Shiho Sannomiya",
         @team=#<Babel::Team:0x53e0f8 ...>>],
      @name="The Children">>,
   #<Babel::Member:0x53c488
    @desc="Psycometrer",
    @name="Shiho Sannomiya",
    @team=
     #<Babel::Team:0x53e0f8
      @chief=
       #<Babel::Member:0x53d5e0
        @desc="Scientist",
        @name="Kohichi Minamoto",
        @team=#<Babel::Team:0x53e0f8 ...>>,
      @desc="Level 7 ESPers",
      @members=
       [#<Babel::Member:0x53d018
         @desc="Psychokino",
         @name="Kaoru Akashi",
         @team=#<Babel::Team:0x53e0f8 ...>>,
        #<Babel::Member:0x53ca50
         @desc="Teleporter",
         @name="Aoi Nogami",
         @team=#<Babel::Team:0x53e0f8 ...>>,
        #<Babel::Member:0x53c488 ...>],
      @name="The Children">>]}

Actions

Kwalify has the command-line '-a action' which perform a certain action to schema definition. Currently only the following actions are provided.

genclass-ruby: Generate class definitions in Ruby.
genclass-java: Generate class definitions in Java.
genclass-php: Generate class definitions in Ruby.

In fact action name represents template filename. For example, action 'genclass-ruby' invokes template file 'kwalify/templates/genclass-ruby.eruby'.

Each action can accept some command-line properties. For example, action 'genclass-ruby' can accept the command-line properties '--module=name', '--parent=name', and so on. Type 'kwalify -h -a action' to show the list of command-line properties the action can accept.

It is able to add your on action template file. The command-line option '-I' (template path) will help you.

Class Definition Generation

Command-line option '-a genclass-ruby' or '-a genclass-java' generates class definition automatically from schema definition in Ruby or Java.

Assume the following data file and schema definition.

address_book.yaml : data file

groups:

  - name:   family
    desc:   my family

  - name:   friend
    desc:   my friends

  - name:   business
    desc:   those who works together

people:

  - name:   Sumire
    group:  family
    birth:  2000-01-01
    blood:  A

  - name:   Shiina
    group:  friend
    birth:  1995-01-01
    email:  shiina@mail.org

  - name:   Sakura
    group:  business
    email:  cherry@mail.net
    phone:  012-345-6789

address_book.schema.yaml : schema definition file

type:  map
class:  AddressBook
desc:  address-book class
mapping:
 "groups":
    type:  seq
    sequence:
      - type:  map
        class:  Group
        desc:  group class
        mapping:
         "name":  { type: str,  required: yes }
         "desc":  { type: str }
 "people":
    type:  seq
    sequence:
      - type:  map
        class:  Person
        desc:  person class
        mapping:
         "name":  { type: str, required: yes }
         "desc":  { type: str }
         "group": { type: str }
         "email": { type: str, pattern: '/@/' }
         "phone": { type: str }
         "birth": { type: date }
         "blood": { type: str, enum: [A, B, O, AB] }
         "deleted": { type: bool, default: false }

Ruby Class Definition

generate class definition

$ kwalify -a genclass-ruby -tf address_book.schema.yaml > address_book.rb

address_book.rb : generated class definition

## address-book class
class AddressBook
  def initialize(hash=nil)
    if hash.nil?
      return
    end
    @groups           = (v=hash['groups']) ? v.map!{|e| e.is_a?(Group) ? e : Group.new(e)} : v
    @people           = (v=hash['people']) ? v.map!{|e| e.is_a?(Person) ? e : Person.new(e)} : v
  end
  attr_accessor :groups           # seq
  attr_accessor :people           # seq
end

## group class
class Group
  def initialize(hash=nil)
    if hash.nil?
      return
    end
    @name             = hash['name']
    @desc             = hash['desc']
  end
  attr_accessor :name             # str
  attr_accessor :desc             # str
end

## person class
class Person
  def initialize(hash=nil)
    if hash.nil?
      @deleted          = false
      return
    end
    @name             = hash['name']
    @desc             = hash['desc']
    @group            = hash['group']
    @email            = hash['email']
    @phone            = hash['phone']
    @birth            = hash['birth']
    @blood            = hash['blood']
    @deleted          = (v=hash['deleted']).nil? ? false : v
  end
  attr_accessor :name             # str
  attr_accessor :desc             # str
  attr_accessor :group            # str
  attr_accessor :email            # str
  attr_accessor :phone            # str
  attr_accessor :birth            # date
  attr_accessor :blood            # str
  attr_accessor :deleted          # bool
  def deleted?      ;  @deleted      ; end
end

example_address_book.rb : example code of using address-book.rb

require 'address_book'
require 'yaml'
require 'pp'

str = File.read('address_book.yaml')
ydoc = YAML.load(str)
addrbook = AddressBook.new(ydoc)

pp addrbook.groups
pp addrbook.people

result

$ ruby example_address_book.rb
[#<Group:0xddf24 @desc="my family", @name="family">,
 #<Group:0xddf10 @desc="my friends", @name="friend">,
 #<Group:0xdde84 @desc="those who works together", @name="business">]
[#<Person:0xdefdc
  @birth=#<Date: 4903089/2,0,2299161>,
  @blood="A",
  @deleted=false,
  @desc=nil,
  @email=nil,
  @group="family",
  @name="Sumire",
  @phone=nil>,
 #<Person:0xdee9c
  @birth=#<Date: 4899437/2,0,2299161>,
  @blood=nil,
  @deleted=false,
  @desc=nil,
  @email="shiina@mail.org",
  @group="friend",
  @name="Shiina",
  @phone=nil>,
 #<Person:0xde8e8
  @birth=nil,
  @blood=nil,
  @deleted=false,
  @desc=nil,
  @email="cherry@mail.net",
  @group="business",
  @name="Sakura",
  @phone="012-345-6789">]

Command-line option '-h -a genclass-ruby' shows the commpand-line properties that template can accept.

show command-line properties

$ kwalify -ha genclass-ruby
  --module=name   :  module name in which class defined
  --parent=name   :  parent class name
  --include=name  :  module name which all classes include
  --initialize=false :  not print initialize() method
  --hashlike      :  include Kwalify::Util::HashLike module

example of command-line properties

$ kwalify -a genclass-ruby --module=My --hashlike

If command-line property '--hashlike' (== '--hashlike=true') is specified, module Kwalify::Util::HashLike is included for each classes generated. That module is defined in 'kwalify/util/hashlike.rb'

Java Class Definition

generate java class definition

$ kwalify -a genclass-java -tf address_book.schema.yaml
generating ./AddressBook.java...done.
generating ./Group.java...done.
generating ./Person.java...done.

AddressBook.java : generated class definition

// generated by kwalify from address_book.schema.yaml

import java.util.*;

/**
 *  address-book class
 */
public class AddressBook {

    private List _groups;
    private List _people;

    public AddressBook() {}

    public AddressBook(Map map) {
        List seq;
        Object obj;
        if ((seq = (List)map.get("groups")) != null) {
            for (int i = 0; i < seq.size(); i++) {
                if ((obj = seq.get(i)) instanceof Map) {
                    seq.set(i, new Group((Map)obj));
                }
            }
        }
        _groups       = seq;
        if ((seq = (List)map.get("people")) != null) {
            for (int i = 0; i < seq.size(); i++) {
                if ((obj = seq.get(i)) instanceof Map) {
                    seq.set(i, new Person((Map)obj));
                }
            }
        }
        _people       = seq;
    }

    public List getGroups() { return _groups; }
    public void setGroups(List groups_) { _groups = groups_; }
    public List getPeople() { return _people; }
    public void setPeople(List people_) { _people = people_; }
}

Group.java : generated class definition

// generated by kwalify from address_book.schema.yaml

import java.util.*;

/**
 *  group class
 */
public class Group {

    private String _name;
    private String _desc;

    public Group() {}

    public Group(Map map) {
        _name         = (String)map.get("name");
        _desc         = (String)map.get("desc");
    }

    public String getName() { return _name; }
    public void setName(String name_) { _name = name_; }
    public String getDesc() { return _desc; }
    public void setDesc(String desc_) { _desc = desc_; }
}

Person.java : generated class definition

// generated by kwalify from address_book.schema.yaml

import java.util.*;

/**
 *  person class
 */
public class Person {

    private String _name;
    private String _desc;
    private String _group;
    private String _email;
    private String _phone;
    private Date _birth;
    private String _blood;

    public Person() {}

    public Person(Map map) {
        _name         = (String)map.get("name");
        _desc         = (String)map.get("desc");
        _group        = (String)map.get("group");
        _email        = (String)map.get("email");
        _phone        = (String)map.get("phone");
        _birth        = (Date)map.get("birth");
        _blood        = (String)map.get("blood");
    }

    public String getName() { return _name; }
    public void setName(String name_) { _name = name_; }
    public String getDesc() { return _desc; }
    public void setDesc(String desc_) { _desc = desc_; }
    public String getGroup() { return _group; }
    public void setGroup(String group_) { _group = group_; }
    public String getEmail() { return _email; }
    public void setEmail(String email_) { _email = email_; }
    public String getPhone() { return _phone; }
    public void setPhone(String phone_) { _phone = phone_; }
    public Date getBirth() { return _birth; }
    public void setBirth(Date birth_) { _birth = birth_; }
    public String getBlood() { return _blood; }
    public void setBlood(String blood_) { _blood = blood_; }
}

ExampleAddressBook.java : example code of using *.java

import java.util.*;
import kwalify.*;

public class ExampleAddressBook {
    public static void main(String args[]) throws Exception {
        // read schema
        String schema_str = Util.readFile("address_book.schema.yaml");
        schema_str = Util.untabify(schema_str);
        Object schema = new YamlParser(schema_str).parse();

        // read document file
        String document_str = Util.readFile("address_book.yaml");
        document_str = Util.untabify(document_str);
        YamlParser parser = new YamlParser(document_str);
        Object document = parser.parse();

        // create address book object
        AddressBook addrbook = new AddressBook((Map)document);

        // show groups
        List groups = addrbook.getGroups();
        if (groups != null) {
            for (Iterator it = groups.iterator(); it.hasNext(); ) {
                Group group = (Group)it.next();
                System.out.println("group name: " + group.getName());
                System.out.println("group desc: " + group.getDesc());
                System.out.println();
            }
        }

        // show people
        List people = addrbook.getPeople();
        if (people != null) {
            for (Iterator it = people.iterator(); it.hasNext(); ) {
                Person person = (Person)it.next();
                System.out.println("person name:  " + person.getName());
                System.out.println("person group: " + person.getGroup());
                System.out.println("person email: " + person.getEmail());
                System.out.println("person phone: " + person.getPhone());
                System.out.println("person blood: " + person.getBlood());
                System.out.println("person birth: " + person.getBirth());
                System.out.println();
            }
        }
    }

}

result

$ javac -classpath '.:kwalify.jar' *.java
$ java  -classpath '.:kwalify.jar' ExampleAddressBook
group name: family
group desc: my family

group name: friend
group desc: my friends

group name: business
group desc: those who works together

person name:  Sumire
person group: family
person email: null
person phone: null
person blood: A
person birth: Tue Feb 01 00:00:00 JST 2000

person name:  Shiina
person group: friend
person email: shiina@mail.org
person phone: null
person blood: null
person birth: Wed Feb 01 00:00:00 JST 1995

person name:  Sakura
person group: business
person email: cherry@mail.net
person phone: 012-345-6789
person blood: null
person birth: null

Command-line option '-h -a genclass-java' shows the commpand-line properties that template can accept.

show command-line properties

$ kwalify -ha genclass-java
  --package=name        :  package name
  --extends=name        :  class name to extend
  --implements=name,... :  interface names to implement
  --dir=path            :  directory to locate output file
  --basedir=path        :  base directory to locate output file
  --constructor=false   :  not print initialize() method

example of command-line properties

$ kwalify -a genclass-java --package=com.example.my --implements=Serializable --basedir=src

References

Usage in Command-Line

### usage1: validate YAML document in command-line
$ kwalify -f schema.yaml document.yaml [document2.yaml ...]
### usage2: validate schema definition in command-line
$ kwalify -m schema.yaml [schema2.yaml ...]

Command-line options:

-h, --help: Print help message.
-v: Print version.
-q: Quiet mode.
-s: (Obsolete. Use '-q' instead.) Silent mode.
-f schema.yaml: Specify schema definition file.
-m: Meta-validation of schema definition.
-t: Expand tab characters to spaces automatically.
-l: Show linenumber on which error found.
-E: Show errors in Emacs-compatible style (implies '-l' option).
-a action: Do action. Currently supported action is 'genclass-ruby' and 'genclass-java'. Try '-ha action' to get help about the action.
-I path1,path2,...: Template path (for '-a').
-P: Enable preceding alias.

Kwalify User's Guide (for Ruby)

Preface

Table of Contents

Schema Definition

Sequence

Mapping

Sequence of Mapping

Mapping of Sequence

Rule and Constraint

Unique constraint

Tips

JSON

Anchor and Alias

Default of Mapping

Merging Mappings

How to in Ruby

Validation

Parsing with Validation

Meta Validation

Validator#validator_hook()

Preceding Alias

Data Binding

Actions

Class Definition Generation

Ruby Class Definition

Java Class Definition

References

Usage in Command-Line