資料驗證好幫手 - JSON Schema Validator

文件大綱：

JSON schema 簡介及作用 - 告訴你什麼是JSON Schema
JSON schema 詳細介紹 - 有完整的文件告訴你JSON Schema中每個propety的作用
JSON Schema範例 - 就像看例句學英文一樣，看範例或許比看文件更好懂
JSON Schema Validator - Ajv套件
Jquery-Validation - 直得參考的的套件

JSON schema 簡介及作用

直接先看一下JSON schema的範例，暖個身

{
   "title":"產品資訊",
   "description":"產品包含商品標號、商品名稱及價錢",
   "type":"object",
   "properties":{
      "pid":{
         "description":"產品的id，是product id的縮寫",
         "type":"integer"
      },
      "name":{
         "description":"產品名稱",
         "type":"string",
         "maxLength": 10
      },
      "price":{
         "type":"number",
         "exclusiveMinimum":0
      }
   },
   "required":[
      "pid",
      "name",
      "price"
   ]
}

JSON Schema就是JSON資料結構的規範，規定一個JSON資料該有哪些資料，包含規定型態、大小範圍等。JSON Schema有官方規範，可以在http://json-schema.org上查看，目前已出到draft-07。

這份文件要介紹的 Ajv (Another JSON Schema Validator) 套件會支援 draft-04/06/07 這幾個版本。

JSON Schema 功用如下：

用於構建人機可讀的文件：
- JSON Schema 可以讓系統讀取，同時也是一個讓人一目瞭然的文件檔，一舉兩得。
用於生成模擬資料：
- 有了JSON Schema，可以自動生成符合規定的資料讓測試程式使用。
用於資料驗證：
- 不需要再寫程式來判斷資料長度跟內容了，所有的邏輯都可以移植到JSON Schema中維護，最後我們會使用ajv這個工具來使用JSON schema進行驗證。

JSON schema 詳細介紹

網路上已經有文件把9成的功能介紹完了，廢話不多說直接看JSON Schema 辭典吧！

其他教學文件：

Ajv: Another JSON Schema Validator

注意：完整的文件可以直接去github上看，這邊會提到比較常用到的內容，或是我有用過的內容。[npm ajv 連結]

這邊有模擬在Nodejs上面執行ajv的連結，可以進去試用看看。

我們已經學會了JSON Schema了，現在直接使用Ajv來比對schema跟data就能驗證資料了，看看下面的範例吧！符合條件的話ajv.validate就會回傳true，反之則false

















var ajv = Ajv();
var schema = {
    "type": "number",
    "oneOf": [
        { "multipleOf": 5 },
        { "multipleOf": 3 }
    ]
};
var data10 = 10;
var data15 = 15;

console.log(ajv.validate(schema, data10)); // true 
console.log(ajv.validate(schema, data15)); // false

如果想知道錯在哪裡，我們就輸出ajv.errors，也是直接看下面範例。

我們在字串長度應該是5的schema中輸入長度是4的字串













var ajv = Ajv();
var schema = {
  "type": "string",
  "minLength": 5
};
var data = "four";

var valid = ajv.validate(schema, data);
if (!valid) console.log(ajv.errors);

資料長度不符合規定時Ajv回傳的錯誤訊息格式如下，大致上看得懂，我們去看下個範例後再解說這些參數是幹嘛的。















[
   {
      "keyword":"minLength",
      "dataPath":"",
      "schemaPath":"#/minLength",
      "params":{
         "limit":5
      },
      "message":"should NOT be shorter than 5 characters"
   }
]

這次的範例有兩個錯誤，分別是2016-12-99不符合date格式，以及fruit欄位應該要是字串卻填入了數字，如果要顯示超過一個以上的error就必須在Options欄位加上{ allErrors: true }，否則它只會回傳第一個error。


























var ajv = new Ajv({ allErrors: true });
var schema = {
    "type": "object",
    "properties": {
        "purchaseDate": { "format": "date" },
        "foods": {
            "type": "object",
            "properties": {
                "fruit": { "type": "string" }
            },
        },
    }
};
var data = {
    "purchaseDate": "2016-12-99",
    "foods": {
        "fruit": 5566
    }
};

var valid = ajv.validate(schema, data);
if (!valid) console.log(ajv.errors);

回傳了兩個錯誤
























[
   {
      "keyword":"format",
      "dataPath":".purchaseDate",
      "schemaPath":"#/properties/purchaseDate/format",
      "params":{
         "format":"date"
      },
      "message":"should match format 'date'"
   },
   {
      "keyword":"type",
      "dataPath":".foods.fruit",
      "schemaPath":"#/properties/foods/properties/fruit/type",
      "params":{
         "type":"string"
      },
      "message":"should be string"
   }
]

想要知道error object的架構，可以看Validation errors，我把裡面的部分內容節錄在下方。

keyword: validation keyword.
dataPath: the path to the part of the data that was validated. By default dataPath uses JavaScript property access notation (e.g., “.prop[1].subProp”). When the option jsonPointers is true (see Options) dataPath will be set using JSON pointer standard (e.g., “/prop/1/subProp”).
schemaPath: the path (JSON-pointer as a URI fragment) to the schema of the keyword that failed validation.
params: the object with the additional information about error that can be used to create custom error messages. [params文件]
message: the standard error message (can be excluded with option messages set to false).

API列表 - 接在ajv後面的api都寫在這。

.compile(Object schema)

validating function and cache the compiled schema for future use，比起每次都用ajv.validate()的執行速度還快，官方文件也說這是The fastest validation call

.errorsText([Array

ajv.errorsText(ajv.errors)這樣的寫法可以把error object轉換成一個錯誤訊息字串，
remote schemas have to be added with addSchema or compiled to be available

.addFormat(String name, String|RegExp|Function|Object format)

使用addFormat定義客製化的format，可以參考下面的範例













var ajv = new Ajv().addFormat('cellphone', '^09[0-9]{2}-[0-9]{3}-[0-9]{3}$');

var schema = {
    "format": "cellphone"
};
var data = '0912-345-678'; // format have to be 09XX-XXX-XXX

var validate = ajv.compile(schema);
console.log(validate(data)); // true

.addKeyword(String keyword, Object definition)

自訂keyword






















ajv.addKeyword('range', {
  type: 'number',
  compile: function (sch, parentSchema) {
    var min = sch[0];
    var max = sch[1];

    return parentSchema.exclusiveRange === true
            ? function (data) { return data > min && data < max; }
            : function (data) { return data >= min && data <= max; }
  }
});

var schema = { "range": [2, 4], "exclusiveRange": true };
var validate = ajv.compile(schema);
console.log(validate(2.01)); // true
console.log(validate(3.99)); // true
console.log(validate(2)); // false
console.log(validate(4)); // false

.addSchema(Array

compile跟addSchema非常像，其實我也分不太出來為啥要分兩個，

addSchema vs schemas

直接傳schema

var validate = jv.addSchema(schema)

傳schema並給予一個key值

var valid = ajv.addSchema(schema, 'mySchema').validate('mySchema', data);

除了addSchema的話，也可以在宣告Ajv時直接assignschemas

var ajv = new Ajv({schemas: [schema1, schema2]});

schemas: an array or object of schemas that will be added to the instance. In case you pass the array the schemas must have IDs in them

.addMetaSchema(Array

這裡有官方對於Meta Schema的介紹，meta-schema是就是JSON Schema的範本，目前最新的meta-schema是draft-07。

至於為何要addMetaSchema我還不是非常清楚

.getSchema(String key)

只透過uri來取得Schema

ajv.getSchema('http://example.com/schemas/schema.json')

Jquery-Validation - 直得參考的的套件

我認為JSON-validator必須要有良好的message回傳機制才實用，所以我找到了一個我個人認為設計蠻好的套件jquery-validation，因為是jquery所以不太適合套用到reactjs專案，但是可以試著引用它的設計模式來打造一個適合自己專案的validator。可以看看Youtube上的jQuery Validation Plugin 播放清單來了解如何使用。

基本上它就是將驗證的rule與要回傳的message分成兩個property互相對應

完形心理學！？讓我們了解“介面設計師”為什麼這樣設計 — 說服客戶與老闆、跟工程師溝通、強化設計概念的有感心理學 — 情況 1 : 為何要留那麼多空白? 害我還要滾動滑鼠(掀桌) 情況 2 : 為什麼不能直接用一頁展現? 把客戶的需求塞滿不就完工啦! (無言) 情況 3: 這種設計好像不錯，但是為什麼要這樣做? (直覺大神告訴我這樣設計，但我說不出來為什麼..) 雖然世界上有許多 GUI 已經走得又長又遠又厲害，但別以為這種古代人對話不會出現，一直以來我們只是習慣這些 GUI 被如此呈現，但為何要這樣設計我們卻不一定知道。由於完形心理學歸納出人類大腦認知之普遍性的規則，因此無論是不是 UI/UX 設計師都很適合閱讀本篇文章。但還是想特別強調，若任職於傳統科技公司，需要對上說服老闆，需要平行說服（資深）工程師，那請把它收進最愛；而習慣套用設計好的 UI 套件，但不知道為何這樣設計的 IT 工程師，也可以透過本文來強化自己的產品說服力。那就開始吧~（擊掌）完形心理學，又稱作格式塔（Gestalt）心理學，於二十世紀初由德國心理學家提出 — 用以說明人類大腦如何解釋肉眼所觀察到的事物，並轉化為我們所認知的物件。它可說是現代認知心理學的基礎，其貫徹的概念就是「整體大於個體的總合 “The whole is other than the sum of the parts.” — Kurt Koffka」。若深究完整的理論將會使本文變得非常的艱澀，因此筆者直接抽取個人認為與 UI 設計較為相關的 7 個原則（如下），並搭配實際案例做說明。有興趣了解全部理論的話可以另外 Google。 1. 相似性 (Similarity) — 我們的大腦會把相似的事物看成一體如果數個元素具有類似的尺寸、體積、顏色，使用者會自動為它們建立起關聯。這是因為我們的眼睛和大腦較容易將相似的事物組織在一起。如下圖所示，當一連串方塊和一連串的圓形並排時，我們會看成（a）一列方塊和兩列圓形（b）一排圓形和兩排三角形。對應用到介面設計上，FB 每則文章下方的按鈕圖標（按讚 Like / 留言Comment / 分享 Share）雖然功能各不相同，但由於它們在視覺上顏色、大小、排列上的相似性，用戶會將它們視認為...

閱讀完整內容

機器人的... 一天...

----------- 未完... 待續... ---------------

搜尋此網誌