Monaco-editor 的 JSON Schema 配置及使用介紹

更新時間：2022年10月08日 10:51:15 作者：對半

這篇文章主要為大家介紹了Monaco-editor 的 JSON Schema 配置及使用介紹，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進(jìn)步，早日升職加薪

JSON Schema 作用用法

jsonschema 是描述 JSON 數(shù)據(jù)的格式并提供驗證結(jié)果，就好比 typescript 對于 JavaScript 的作用。

JSON Schema Core Vocabulary

$schema

$schema 關(guān)鍵字既用作JSON模式方言標(biāo)識符，也用作資源的標(biāo)識符，資源本身就是一個JSON模式，它描述了為JSON編寫的有效模式集。

該關(guān)鍵字的值必須是一個規(guī)范的URI。如果這個URI標(biāo)識了一個可檢索的資源，該資源的媒體類型應(yīng)該是 application/schema+json。

$schema 關(guān)鍵字應(yīng)該在文檔根模式對象中使用，并且可以在嵌入模式資源的根模式對象中使用。它絕對不能出現(xiàn)在非資源根模式對象中。如果文檔根模式中沒有，則產(chǎn)生的行為是由實現(xiàn)定義的。

$id

$id 關(guān)鍵字用它的規(guī)范URI標(biāo)識一個模式資源，這個URI是一個標(biāo)識符，而不一定是網(wǎng)絡(luò)定位器。對于網(wǎng)絡(luò)可尋址URL，不會從其規(guī)范URI下載。

$id 不能包含非空的片段，也不應(yīng)該包含空的片段。絕對URI形式必須被認(rèn)為是規(guī)范URI，無論是否存在空片段。當(dāng)前允許使用空片段，因為舊的元模式的 $id (或以前的id)中有一個空片段。未來的草案可能會完全禁止 $id 中的空片段。

在子模式中出現(xiàn) $id 表示子模式在單個模式文檔中構(gòu)成一個不同的模式資源。此外，如果子模式中的 $id 是一個相對URI引用，則解析該引用的基URI是父模式資源的URI。
如果沒有父模式對象顯式地將自己標(biāo)識為具有 $id 的資源，則基URI就是整個文檔的基URI。

$ref

$ref 關(guān)鍵字是一個應(yīng)用程序，用于引用靜態(tài)標(biāo)識的模式。它的結(jié)果是引用模式的結(jié)果。注意，這種確定結(jié)果的定義意味著其他關(guān)鍵字可以與 $ref 一起出現(xiàn)在同一個模式對象中。

$ref 關(guān)鍵字的值必須是一個URI-Reference字符串，可以是相對當(dāng)前模式內(nèi)部地址，也可以是網(wǎng)絡(luò)地址。它根據(jù)當(dāng)前URI基進(jìn)行解析，生成要應(yīng)用的模式的URI。在模式加載時執(zhí)行這種解析是安全的，因為計算實例的過程不能改變引用解析的方式。

$dynamicRef

$dynamicRef 關(guān)鍵字是一個應(yīng)用程序，它允許將完整的解析延遲到運行時，在計算實例時，每次遇到它都會被解析。

與 $dynamicAnchor 一起，$dynamicRef 實現(xiàn)了一種協(xié)作擴展機制，它主要用于遞歸模式(引用自身的模式)。擴展點和運行時確定的擴展目標(biāo)都是用 $dynamicAnchor 定義的，并且只有在使用 $dynamicRef 引用時才顯示運行時動態(tài)行為。

$dynamicRef 屬性的值必須是一個URI-Reference字符串。它根據(jù)當(dāng)前URI基進(jìn)行解析，生成用作運行時解析起點的URI。

如果最初解析的起點URI包含一個由 $dynamicAnchor 關(guān)鍵字創(chuàng)建的片段，則初始URI必須被動態(tài)作用域中最外層模式資源的URI(包括片段)所替換，該資源定義了一個與 $dynamicAnchor 同名的片段。

否則，它的行為與 $ref 相同，不需要運行時解析。

簡單來說，$dynamicRef 就是為了運行時遞歸解析 $dynamicAnchor 所定義的模式。

$anchor / $dynamicAnchor

使用JSON指針片段需要了解模式的結(jié)構(gòu)。當(dāng)編寫模式文檔意圖提供可重用的模式時，最好使用不綁定到任何特定結(jié)構(gòu)位置的普通名稱片段。這允許重新定位子模式，而不需要更新JSON指針引用。

$anchor 和 $dynamicAnchor 關(guān)鍵字用于指定這樣的片段。它們是標(biāo)識符關(guān)鍵字，只能用于創(chuàng)建普通名稱片段，而不是像 $id 那樣的絕對uri。

除非需要指定 $dynamicAnchor，否則就使用 $anchor。

{
    "$id": "https://example.net/root.json",
    "items": {
        "type": "array",
        "items": { "$ref": "#item" }
    },
    "$defs": {
        "single": {
            "$anchor": "item",
            "type": "object",
            "additionalProperties": { "$ref": "other.json" }
        }
    }
}

$defs

$defs 關(guān)鍵字為當(dāng)前模式保留了一個位置，以便將可重用的JSON模式內(nèi)聯(lián)到更通用的模式中。關(guān)鍵字不直接影響驗證結(jié)果。

該關(guān)鍵字的值必須是一個對象。該對象的每個成員值必須是有效的JSON Schema。

例如，下面是一個描述正整數(shù)數(shù)組的模式，其中正整數(shù)約束是 $defs 中的子模式:

{
    "type": "array",
    "items": { "$ref": "#/$defs/positiveInteger" },
    "$defs": {
        "positiveInteger": {
            "type": "integer",
            "exclusiveMinimum": 0
        }
    }
}

關(guān)鍵字

JSON Schema包含一些關(guān)鍵字，它們不是嚴(yán)格用于驗證，而是用于描述模式的各個部分。這些“注釋”關(guān)鍵字都不是必需的，但是作為良好的實踐，鼓勵使用它們，并且可以使您的模式“自文檔化”。

type

該關(guān)鍵字的值必須是字符串或數(shù)組。如果它是一個數(shù)組，數(shù)組的元素必須是字符串并且必須是唯一的。字符串值必須是六種基本類型(null， boolean， object， array， number，或 String )中的一種，或者是匹配任何小數(shù)部分為零的數(shù)字的 integer。如果 type 的值是一個字符串，那么如果實例的類型與該字符串值所表示的類型匹配，則實例驗證成功。如果 type 的值是一個數(shù)組，那么實例驗證成功的前提是它的類型與所指示的任何類型相匹配

title & description

這兩個關(guān)鍵字的值必須是一個字符串。
這兩個關(guān)鍵字都可以用來用該用戶界面產(chǎn)生的數(shù)據(jù)信息裝飾用戶界面。標(biāo)題最好是簡短的，而描述將解釋此模式所描述的實例的目的。

default

default 關(guān)鍵字指定一個默認(rèn)值。此值不用于在驗證過程中填充缺失的值。文檔生成器或表單生成器等非驗證工具可能使用此值向用戶提示如何使用該值。但是，default 通常用于表示如果缺少一個值，那么該值在語義上與使用默認(rèn)值時的值相同。default 的值應(yīng)該根據(jù)它所在的模式進(jìn)行驗證，但這不是必需的。

examples

該關(guān)鍵字的值必須是一個數(shù)組。對數(shù)組中的值沒有任何限制。
該關(guān)鍵字可用于提供與特定模式相關(guān)聯(lián)的示例JSON值，以便演示使用方法。建議這些值對關(guān)聯(lián)的模式有效。
如果存在，實現(xiàn)可以使用 default 值作為額外的示例。如果沒有 examples，default 仍然可以以這種方式使用。證，但這不是嚴(yán)格要求的。不需要復(fù)制 examples 數(shù)組中的默認(rèn)值，因為 default 將被視為另一個示例。

deprecated

deprecated 關(guān)鍵字是一個布爾值，表示該關(guān)鍵字所應(yīng)用的實例值不應(yīng)被使用，將來可能會被刪除。

readOnly & writeOnly

布爾型關(guān)鍵字 readOnly 和 writeOnly 通常在API上下文中使用。
readOnly 表示不修改該值。它可以用來表示更改值的PUT請求將導(dǎo)致400 Bad request響應(yīng)。
writeOnly 表示可以設(shè)置一個值，但將保持隱藏。In可以用來表示可以用PUT請求設(shè)置一個值，但是在用GET請求檢索該記錄時不包括它。

$comment

$comment 關(guān)鍵字嚴(yán)格用于向模式添加注釋。它的值必須總是一個字符串。與注釋標(biāo)題、描述和示例不同，JSON模式實現(xiàn)不允許為其附加任何含義或行為，甚至可以隨時剝離它們。因此，它們用于給JSON模式的未來編輯器留下注釋，但不應(yīng)用于與模式的用戶通信。

enum

enum 關(guān)鍵字用于將一個值限制為一組固定的值。它必須是一個至少有一個元素的數(shù)組，其中每個元素都是唯一的。
如果 enum 數(shù)組的值包含該屬性的值，則對該關(guān)鍵字驗證成功。

const

const 關(guān)鍵字用于將一個值限制為單個值。
該關(guān)鍵字的值可以是任何類型，等同于只有一個值的 enum。
如果實例的值等于該關(guān)鍵字的值，則實例驗證成功。

媒體類型關(guān)鍵字

{
    "type": "string",
    "contentEncoding": "base64",
    "contentMediaType": "image/png"
}

contentMediaType

如果實例是字符串，則此屬性指示字符串內(nèi)容的媒體類型。如果存在 contentEncoding，則此屬性描述已解碼的字符串。
該屬性的值必須是一個字符串，必須是一個媒體類型。

contentEncoding

此屬性的值必須是一個字符串。
如果實例值是字符串，此屬性定義該字符串應(yīng)被解釋為編碼的二進(jìn)制數(shù)據(jù)，并使用此屬性命名的編碼進(jìn)行解碼。
可接受的值是 7bit, 8bit, binary, quote-printable, base16, base32 和 base64。如果未指定，則編碼與包含JSON文檔的編碼相同。

組合模式

allOf

該關(guān)鍵字的值必須是非空數(shù)組。數(shù)組的每一項必須是有效的JSON Schema。
如果實例成功地驗證了由該關(guān)鍵字的值定義的所有模式，則該實例就成功地驗證了該關(guān)鍵字。

// 示例
{
  "reg": {
    "type": "string",
    "allOf": [
      { "maxLength": 10 },
      { "minLength": 3 }
    ]
  }
}

maxLength 和 minLength 都需要滿足才驗證成功。

anyOf

該關(guān)鍵字的值必須是非空數(shù)組。數(shù)組的每一項必須是有效的JSON Schema。
如果實例成功地驗證了由該關(guān)鍵字的值定義的至少一個模式，則該實例就成功地驗證了該關(guān)鍵字。注意，在收集注釋時，必須檢查所有子模式，以便從每個成功驗證的子模式收集注釋。

// 示例
{
  "reg": {
    "anyOf": [
      { "type": "number", "minimum": 20 },
      { "type": "string", "minLength": 3 }
    ]
  }
}

type & minimum 和 type & minLength 兩個條件至少滿足一個即驗證成功。

oneOf

該關(guān)鍵字的值必須是非空數(shù)組。數(shù)組的每一項必須是有效的JSON Schema。
如果一個實例僅對由該關(guān)鍵字的值定義的一個模式進(jìn)行了成功驗證，則該實例對該關(guān)鍵字進(jìn)行了成功驗證。

// 示例
{
  "reg": {
    "type": "string",
    "oneOf": [
      { "maxLength": 10 },
      { "minLength": 3 }
    ]
  }
}

maxLength 和 minLength 只能滿足其中一個才能驗證成功。

not

該關(guān)鍵字的值必須是一個有效的JSON模式。
如果一個實例對該關(guān)鍵字定義的模式驗證失敗，則該實例對該關(guān)鍵字有效。

// 示例
{
  "reg": {
    "type": "string",
    "not": { "minLength": 3 }
  }
}

不能滿足 minLength 才能驗證成功。

子模式條件驗證

if-then-else

if、then、else 這三個關(guān)鍵字必須是有效的 JSON Schema。

如果 if 模式驗證成立，則使用 then 模式，失敗則使用 else 模式。

如果 if 不存在，則 then 與 else 關(guān)鍵字不起作用。

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "description": "test json schema",
  "type": "object",
  "title": "Schema",
  "properties": {
    "foo": { "type": "string" },
    "bar1": { "type": "string" },
    "bar2": { "type": "string" }
  },
  "if": {
    "properties": {
      "foo": { "const": "123" }
    }
  },
  "then": {
    "required": [ "bar1" ]
  },
  "else": {
    "required": [ "bar2" ]
  }
}

以上 schema，如果 foo 的值為 '123'，則 bar1 是必須存在的，否則 bar2 是必須存在的。

dependentSchemas

dependentSchemas 關(guān)鍵字在給定屬性出現(xiàn)時有條件地應(yīng)用子模式。該模式的應(yīng)用方式與 allOf 應(yīng)用模式相同。沒有合并或擴展任何內(nèi)容。兩個模式都獨立應(yīng)用。

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "credit_card": { "type": "number" }
  },
  "required": ["name"],
  "dependentSchemas": {
    "credit_card": {
      "properties": {
        "billing_address": { "type": "string" }
      },
      "required": ["billing_address"]
    }
  }
}

以上示例，如果 credit_card 存在，則 billing_address 也必須以字符串存在。

dependentRequired

該關(guān)鍵字的值必須是一個對象。此對象中的屬性(如果有)必須是數(shù)組。每個數(shù)組中的元素(如果有的話)必須是字符串，并且必須是唯一的。

該關(guān)鍵字指定在出現(xiàn)特定其他屬性時所需的屬性。他們的要求取決于其他屬性的存在。

如果對于實例中出現(xiàn)的每個名稱以及該關(guān)鍵字值中作為名稱出現(xiàn)的每個名稱，對應(yīng)數(shù)組中的每個項也是實例中屬性的名稱，則驗證成功。

省略此關(guān)鍵字與空對象的行為相同

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "credit_card": { "type": "number" },
    "billing_address": { "type": "string" }
  },
  "required": ["name"],
  "dependentRequired": {
    "credit_card": ["billing_address"]
  }
}

數(shù)值驗證

multipleOf

multipleOf 的值必須是一個數(shù)字，且必須嚴(yán)格大于0。
數(shù)值實例只有在除以該關(guān)鍵字的值得到整數(shù)時才有效

maximum

maximum 的值必須是一個數(shù)字，表示數(shù)值實例的包含上限。
如果實例是一個數(shù)字，則此關(guān)鍵字僅在實例小于或恰好等于 maximum 時驗證成功。

exclusiveMaximum

exclusivemmaximum 的值必須是一個數(shù)字，表示數(shù)值實例的排他上限。
如果實例是一個數(shù)字，那么該實例只有在其值嚴(yán)格小于(不等于)時才有效。

minimum

minimum 的值必須是一個數(shù)字，表示數(shù)值實例的包含下限。
如果實例是一個數(shù)字，則此關(guān)鍵字僅在實例大于或恰好等于 minimum 時驗證成功。

exclusiveMinimum

exclusivminimum 的值必須是一個數(shù)字，表示數(shù)值實例的排他下限。
如果實例是一個數(shù)字，那么只有當(dāng)它的值嚴(yán)格大于(不等于)時，該實例才有效。

字符串驗證

maxLength

該關(guān)鍵字的值必須是非負(fù)整數(shù)。
如果字符串實例的長度小于或等于該關(guān)鍵字的值，則該字符串實例對該關(guān)鍵字有效。

minLength

該關(guān)鍵字的值必須是非負(fù)整數(shù)。
如果字符串實例的長度大于或等于該關(guān)鍵字的值，則該字符串實例對該關(guān)鍵字有效。
省略這個關(guān)鍵字與值為0的行為相同

pattern

該關(guān)鍵字的值必須為字符串。該字符串應(yīng)該是一個有效的正則表達(dá)式。
如果正則表達(dá)式成功匹配字符串實例，則認(rèn)為該字符串實例有效。

{
  "regex": {
    "type": "string",
    "pattern": "^\\d+$"
  }
}

format

format關(guān)鍵字允許對常用的某些類型的字符串值進(jìn)行基本語義標(biāo)識。例如，因為JSON沒有“DateTime”類型，所以需要將日期編碼為字符串。Format允許模式作者指出應(yīng)該將字符串值解釋為日期。默認(rèn)情況下，format只是一個注釋，不影響驗證。

{
  "date": {
    "type": "string",
    "format": "date"
  }
}

format 支持的類型： built-in-formats

數(shù)組驗證

prefixItems

prefixItems 的值必須是一個有效的JSON schema的非空數(shù)組，主要用于對元組的校驗。

如果實例的每個元素都在相同位置對模式進(jìn)行驗證(如果有的話)，則驗證成功。此關(guān)鍵字不限制數(shù)組的長度。如果數(shù)組長度大于該關(guān)鍵字的值，則該關(guān)鍵字只驗證匹配長度的前綴。

該關(guān)鍵字產(chǎn)生的注釋值是該關(guān)鍵字應(yīng)用子模式的最大索引。如果子模式應(yīng)用于實例的每個索引，例如由 items 鍵產(chǎn)生，則該值可能為布爾值true

{
  "type": "array",
  "prefixItems": [
    { "type": "number" },
    { "type": "string" },
    { "enum": ["Street", "Avenue", "Boulevard"] },
    { "enum": ["NW", "NE", "SW", "SE"] }
  ]
}

如果同級的 items 關(guān)鍵字的值為 false，則該關(guān)鍵字的實例值不可超出 prefixItems 的長度。

items

該關(guān)鍵字可以是 array or object or boolean，用來定義數(shù)組內(nèi)元素的類型。

array：不能為空，可以為每個位置的元素定義模式或者實例，如果為空對象或者后面元素未定義則為任意類型。這里的數(shù)組類型雖然文檔上面沒有提到，但是測試下來，如果沒有其它的需求，與 prefixItems 的效果一樣。

object：可以使用 allOf、anyOf 等批量定義模式

boolean：true 為任意類型，false 則數(shù)組為空

省略這個關(guān)鍵字與值為true的行為相同

maxItems

該關(guān)鍵字的值必須是非負(fù)整數(shù)。
如果數(shù)組長度的大小小于或等于此關(guān)鍵字的值，則該數(shù)組實例對 maxItems 有效。

minItems

該關(guān)鍵字的值必須是非負(fù)整數(shù)。
如果數(shù)組長度的大小大于或等于該關(guān)鍵字的值，則該數(shù)組實例對 minItems 有效。
省略這個關(guān)鍵字與值為0的行為相同

uniqueItems

該關(guān)鍵字的值必須為布爾值。
如果該關(guān)鍵字的布爾值為false，則實例驗證成功。如果它的布爾值為true，則實例成功驗證其所有元素是否唯一。
省略這個關(guān)鍵字與false值具有相同的行為

contains

包含模式只需要對數(shù)組中的一個或多個項進(jìn)行驗證。

{
   "type": "array",
   "contains": { "type": "number" }
}
// ["life", "universe", "everything", 42] // 有效

maxContains / minContains

minContains 和 maxContains 可以與 contains 一起使用，以進(jìn)一步指定模式匹配包含約束的次數(shù)。這些關(guān)鍵字可以是包括零在內(nèi)的任何非負(fù)數(shù)。

{
   "type": "array",
   "contains": { "type": "number" },
   "minContains": 2,
   "maxContains": 3
}
// ["life", "universe", "everything", 42] // 無效
// ["life", "universe", "everything", 42, 21] // 有效
// ["life", "universe", "everything", 42, 21, 12, 1] // 無效

對象驗證

properties

對象上的屬性(鍵-值對)是使用 properties 關(guān)鍵字定義的。屬性的值是一個對象，其中每個鍵是屬性的名稱，每個值是用于驗證該屬性的模式。任何不匹配 properties 關(guān)鍵字中的任何屬性名稱的屬性都將被此關(guān)鍵字忽略。

{
  "type": "object",
  "properties": {
    "number": { "type": "number" },
    "street_name": { "type": "string" },
    "street_type": { "enum": ["Street", "Avenue", "Boulevard"] }
  }
}

patternProperties

有時給定特定類型的屬性名，值應(yīng)該匹配特定的模式。這就是 patternProperties 發(fā)揮作用的地方:它將正則表達(dá)式映射到模式。如果屬性名與給定的正則表達(dá)式匹配，則屬性值必須根據(jù)相應(yīng)的模式進(jìn)行驗證。

{
  "type": "object",
  "patternProperties": {
    "^S_": { "type": "string" },
    "^I_": { "type": "integer" }
  }
}
// { "S_25": "This is a string" } // 有效
// { "S_0": 42 } // 無效

additionalProperties

additionalProperties 關(guān)鍵字用于控制額外內(nèi)容的處理，也就是說，名稱沒有在 properties 關(guān)鍵字中列出或匹配 patternProperties 關(guān)鍵字中的任何正則表達(dá)式的屬性。默認(rèn)允許任何附加屬性。
additionalProperties 關(guān)鍵字的值是一個模式，將用于驗證實例中未被 properties或patternProperties 匹配的任何屬性。將 additionalProperties 模式設(shè)置為false意味著不允許使用其他屬性。

{
  "type": "object",
  "properties": {
    "number": { "type": "number" }
  },
  "additionalProperties": false
}
// { "number": 1600 } // 有效
// { "number": 1600, "street_name": "Pennsylvania" } // 無效

可以使用非布爾模式在實例的附加屬性上添加更復(fù)雜的約束。例如，可以允許附加的值都是字符串的屬性:

{
  "type": "object",
  "properties": {
    "number": { "type": "number" }
  },
  "additionalProperties": { "type": "string" }
}

propertyNames

屬性的名稱可以根據(jù)模式進(jìn)行驗證，而不管其值如何。如果您不想強制執(zhí)行特定的屬性，但希望確保這些屬性的名稱遵循特定的約定，那么這可能很有用。例如，您可能希望強制所有名稱都是有效的ASCII令牌，以便它們可以在特定的編程語言中用作屬性。

{
  "type": "object",
  "propertyNames": {
    "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
  }
}
// { "_a_proper_token_001": "value" } // 有效

maxProperties

該關(guān)鍵字的值必須是非負(fù)整數(shù)。
如果對象實例的屬性數(shù)量小于或等于該關(guān)鍵字的值，則對象實例針對 maxProperties 是有效的。

minProperties

該關(guān)鍵字的值必須是非負(fù)整數(shù)。
如果對象實例的屬性數(shù)量大于或等于該關(guān)鍵字的值，則對象實例針對 minProperties 是有效的。
省略這個關(guān)鍵字與值為0的行為相同

required

該關(guān)鍵字的值必須是一個數(shù)組。這個數(shù)組的元素(如果有的話)必須是字符串，并且必須是唯一的。
如果數(shù)組中的每個項都是實例中的屬性名稱，則對象實例針對此關(guān)鍵字有效。
省略此關(guān)鍵字與空數(shù)組的行為相同