Kwalify User's Guide (for Ruby)

release: $Release: $

1   Schema Definition

This section describes how to define schema definition of YAML.

1-1   Sequence

type:   seq
sequence:
  - type:   str

- foo
- bar
- baz

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

- foo
- 123
- baz

$ 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

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

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

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

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

$ 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

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

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

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

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

$ 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

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

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

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

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

$ 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.

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.

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

- 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

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

- 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

$ 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.

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 }

- 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

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

- 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

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