Kwalify User's Guide (for Ruby)

release: $Release: $

1   Schema Definition

This section describes how to define schema definition of YAML.

1-1   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'.

1-2   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.

1-3   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.

1-4   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.

1-5   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.

1-6   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'.