YAML与Schema语法

JSON的语法是YAML语法的子集，因此大部分的JSON文件都可以被YAML的解析器解析。 由于YAML的运作主要依赖缩进来决定结构，且字符串不需要双引号，写出的Schema会更加精简，更适合写在文档字符串中。

Validr中使用JSON格式表示Schema， 框架中则用的是YAML，是为了适合不同的使用环境。

学习Schema语法需要先学会基本的JSON和YAML语法，YAML语法比JSON语法略复杂一些，可以通过 YAML 语言教程对YAML语法进行初步了解。

之后可以看一下Validr中的Schema语法， Schema语法是基于JSON的，并且与实际数据结构相同，很容易掌握。

然后再转换到YAML格式的Schema，新手学习过程中可能会遇到一些问题， 这里总结了一些与Schema相关的语法，方便上手。

YAML解析器

YAML中有一些特殊符号，@ 是YAML的保留符号，& 用于表示 锚， 这两个与Schema语法有冲突，框架对YAML解析器进行了修改，将 @，& 视为普通字符串，同时不再支持YAML的锚语法。

列表

注意: '-' 后面要有一个空格或换行。

简单的列表:

  1. # tags
  2. - &unique&minlen=1
  3. - str

嵌套的列表:

  1. # time_table
  2. # 星期一
  3. - - 上午写BUG
  4.   - 下午改BUG
  5.   - 晚上又写BUG
  6. # 星期二
  7. - - 上午改昨天的BUG
  8.   - 下午又写一堆BUG
  9.   - 晚上改不完的BUG
  10. # ...
  12. # schema_of_time_table
  13. - &minlen=7&maxlen=7 # 一周七天
  14. - - &minlen=3&maxlen=3 # 每天有三个时间段
  15.   - str&optional # 这个时间段的安排

字典

注意: ':' 后面要有一个空格或换行。

简单的字典:

  1. user:
  2.     id?int: user id
  3.     name?str: user name

嵌套的字典:

  1. friends:
  2.     best:
  3.         $self: best friend
  4.         id?int: user id
  5.         name?str: user name
  6.     bad:
  7.         $self: bad friend
  8.         id?int: user id
  9.         name?str: user name
  11. friends:
  12.     best@user: best friend
  13.     bad@user: bad friend

复杂的嵌套

列表里面是字典:

  1. - my friends
  2. - id?int: user id
  3.   name?str: user name
  5. - my friends
  6. - @user

字典里面有列表:

  1. friends:
  2.     - my friends
  3.     - id?int: user id
  4.       name?str: user name
  6. friends:
  7.     - my friends
  8.     - @user

引用

  1. $shared:
  2.     userid: int
  3.     tags:
  4.         - &unique&minlen=1
  5.         - str
  6.     user:
  7.         id?int: user id
  8.         name?str: user name

下面的可以引用上面的:

  1. $shared:
  2.     userid: int
  3.     user:
  4.         id@userid: user id
  5.         name?str: user name

混合

  1. $shared:
  2.     paging:
  3.         page_num?int&min=1&default=1: 第几页
  4.         page_size?int&min=1&default=10: 每页的数量
  5.     query:
  6.         $self@paging: 查询参数
  7.         tag?str: 标签
  8.         date?date: 日期