介紹

不知道大家在寫一些 JSON 配置時會不會經(jīng)常覺得麻煩，每次都要打開文檔去核對字段名稱對不對、結(jié)尾有沒有 s、結(jié)構(gòu)是否正確、是不是數(shù)組等問題。然而我最近發(fā)現(xiàn)一些開源項目生成的配置文件中都開始使用 JSON schema 來規(guī)范配置文件，IDE 也會對 JSON 配置進(jìn)行提示和檢查，真香。本文介紹下 JSON schema 的使用方法和使用場景。

JSON schema 是一套對 JSON 進(jìn)行規(guī)范化的方案，在 JSON 文件中聲明 schema 即可使用 JSON schema 檢查 JSON 文件的正確性，且大部分主流 IDE 可對 JSON 文件進(jìn)行屬性提示、字段校驗。

使用

JSON schema 的使用方式非常簡單，只需要在 JSON 文件中添加 $schema 字段，指定 schema 文件地址即可。

{
    "$schema": "https://json.schemastore.org/jsconfig"
}

添加后，IDE 或其它工具將會根據(jù)目標(biāo)地址中的 schema 定義對 JSON 文件進(jìn)行檢查和智能提示等等。

如上圖，會在編輯時自動提示字段名稱，hover 字段名顯示字段解釋，類型錯誤的字段顯示警告等等。

除了上述使用網(wǎng)絡(luò)地址來標(biāo)識 schema 文件外，還可以使用本地文件地址，比如：

{
    "$schema": "./my-schema.json"
}

schemastore

schemastore 中存儲了很多項目常用的 JSON schema

地址：https://www.schemastore.org/json/

里面包含了常見的 prettier、eslint、jsconfig、tsconfig、各類 ci/cd、lerna 等工具的配置文件，可直接引用。

并且還提供了所有支持的清單：https://www.schemastore.org/api/json/catalog.json

開源項目可在 https://github.com/schemastore/schemastore/中提交自己的 schema。

當(dāng)然也可以自己管理，只需提供可訪問的網(wǎng)絡(luò)地址即可。

編寫 schema

編寫 schema 其實也很簡單，JSON schema 也存在幾套規(guī)范，我目前能看到的包括：

JSON Schema Draft 4

JSON Schema Draft 7

JSON Schema Draft 8

JSON Schema Draft 2020-12

上述對應(yīng)的 schema 文件都可在 schemastore 中找到。

編寫時同樣可指定編寫文件的 $schema，注意草案 8 和 2020-12 使用到了 $recursiveRef，而 vsc 暫不支持，所以下面使用 Draft 7 規(guī)范來進(jìn)行編寫。

{
    "$schema": "https://json-schema.org/draft-07/schema",
    "$id": "my-schema"
}

可使用 $id 來表示 schema。

編寫主要使用大兩個屬性，一個是 properties，用于定義屬性，一個是 definitions，用于定義 schema 片段（可理解為變量）。

properties

先看下 properties 的使用：

{
    "properties": {
        "name": {
            "type": "string",
            "title": "this is your name"
        },
        "age": {
            "type": "number",
            "title": "this is your age"
        }
    }
}

上面定義了 json 中的兩個屬性，name 為字符串，title 為數(shù)字，title 為屬性的描述，也可以使用 description。

然后我們在 json 文件中即可使用 $schema 來引用我們剛剛定義的 schema，如下：

{
    "$schema": "my-schema.json",
    "name": "嘿嘿",
    "age": 32
}

definitions

definitions 一般用于定義一些復(fù)雜類型，方便在 schema 中復(fù)用定義：

{
    "definitions": {
        "name": {
            "type": "object",
            "properties": {
                "firstName": {
                    "description": "First name",
                    "type": "string"
                },
                "lastName": {
                    "description": "Last name",
                    "type": "string"
                },
                "middleName": {
                    "type": "string",
                    "description": "Middle name"
                }
            }
        }
    }
}

上述代碼及定義里一個 name 的 schema 字段，包含 firstName、lastName、middleName 三個屬性，然后我們需要在 properties 中引用它：

{
    "properties": {
        "fullName": {
            "$ref": "#/definitions/name"
        }
    }
}

$ref 代表此處定義為引用，屬性為引用的地址，# 為該 schema 文件的根，此處即為引用 definitions 中 name 的定義。

然后我們便可在 json 文件中使用我們剛剛定義的 schema：

{
    "$schema": "my-schema.json",
    "fullName": {
        "firstName": "嘿",
        "lastName": "嘿"
    }
}

除了上述的屬性定義等， JSON schema 還提供了其它的一些定義，如數(shù)組、數(shù)字的范圍等等。

總結(jié)

JSON schema 可以用來規(guī)范我們的配置文件，借助 IDE 的智能提示還能降低我們編寫配置文件的成本，如果存在這方面的需求，趕緊用起來吧。

參考

JSON Schema

Understanding JSON Schema

以上就是JSON schema配置規(guī)范使用教程的詳細(xì)內(nèi)容，更多關(guān)于JSON schema配置規(guī)范的資料請關(guān)注腳本之家其它相關(guān)文章！

最新評論