# 格式校验
¥Format validation
# 字符串格式
¥String formats
从版本 7 开始,Ajv 不包含 JSON Schema 规范定义的格式 - 这些和其他几种格式由 ajv-formats (opens new window) 插件提供。
¥From version 7 Ajv does not include formats defined by JSON Schema specification - these and several other formats are provided by ajv-formats (opens new window) plugin.
要从此插件添加所有格式:
¥To add all formats from this plugin:
有关更多详细信息,请参阅 ajv-formats (opens new window) 文档。
¥See ajv-formats (opens new window) documentation for further details.
建议不要对不受信任的数据使用 "format" 关键字实现,因为它们可能使用潜在不安全的正则表达式(即使已知问题已修复) - see 重拒绝攻击。
¥It is recommended NOT to use "format" keyword implementations with untrusted data, as they may use potentially unsafe regular expressions (even though known issues are fixed) - see ReDoS attack.
不可信数据的格式校验
如果你需要使用 "format" 关键字来校验不受信任的数据,你必须评估它们对你的校验场景的适用性和安全性。
¥If you need to use "format" keyword to validate untrusted data, you MUST assess their suitability and safety for your validation scenarios.
ajv-formats (opens new window) 中定义了以下格式,用于使用 "format" 关键字进行字符串校验:
¥The following formats are defined in ajv-formats (opens new window) for string validation with "format" keyword:
date:根据 RFC3339 (opens new window) 的完整日期。
¥date: full-date according to RFC3339 (opens new window).
time:带有可选时区的时间。
¥time: time with optional time-zone.
date-time:来自同一来源的日期时间(时区是强制性的)。
¥date-time: date-time from the same source (time-zone is mandatory).
duration:从 RFC3339 (opens new window) 开始的持续时间
¥duration: duration from RFC3339 (opens new window)
uri:完整的 URI。
¥uri: full URI.
uri-reference:URI 引用,包括完整和相对 URI。
¥uri-reference: URI reference, including full and relative URIs.
uri-template:根据 RFC6570 (opens new window) 的 URI 模板
¥uri-template: URI template according to RFC6570 (opens new window)
网址(已弃用):网址记录 (opens new window)。
¥url (deprecated): URL record (opens new window).
email:电子邮件地址。
¥email: email address.
hostname:根据 RFC1034 (opens new window) 的主机名。
¥hostname: host name according to RFC1034 (opens new window).
ipv4:IP 地址 v4。
¥ipv4: IP address v4.
ipv6:IP 地址 v6。
¥ipv6: IP address v6.
regex:通过将字符串传递给 RegExp 构造函数来测试字符串是否是有效的正则表达式。
¥regex: tests whether a string is a valid regular expression by passing it to RegExp constructor.
uuid:根据 RFC4122 (opens new window) 的通用唯一标识符。
¥uuid: Universally Unique Identifier according to RFC4122 (opens new window).
json-pointer:根据 RFC6901 (opens new window) 的 JSON 指针。
¥json-pointer: JSON-pointer according to RFC6901 (opens new window).
relative-json-pointer:根据 这个草案 (opens new window) 的相对 JSON 指针。
¥relative-json-pointer: relative JSON-pointer according to this draft (opens new window).
ajv-formats-draft2019 中的其他格式
JSON 结构草案 07 还为具有国际字符的 URL、主机名和电子邮件定义了格式 iri
、iri-reference
、idn-hostname
和 idn-email
。这些格式在 ajv-formats-draft2019 (opens new window) 插件中可用。
¥JSON Schema draft-07 also defines formats iri
, iri-reference
, idn-hostname
and idn-email
for URLs, hostnames and emails with international characters. These formats are available in ajv-formats-draft2019 (opens new window) plugin.
# 用户定义的格式
¥User-defined formats
你可以使用 addFormat 方法添加和替换任何格式:
¥You can add and replace any formats using addFormat method:
ajv.addFormat("identifier", /^a-z\$_[a-zA-Z$_0-9]*$/)
Ajv 还允许定义仅应用于数字的格式:
¥Ajv also allows defining the formats that would be applied to numbers only:
ajv.addFormat("byte", {
type: "number",
validate: (x) => x >= 0 && x <= 255 && x % 1 == 0,
})
# 格式和独立校验代码
¥Formats and standalone validation code
如果你使用 ajv-formats (opens new window) 包中的格式,则将立即支持 独立校验代码。
¥If you use formats from ajv-formats (opens new window) package, standalone validation code will be supported out of the box.
独立代码和 Ajv 版本
你需要确保 ajv-formats 导入与你在应用中使用的 ajv 版本和代码相同的版本和代码,以便独立校验代码正常工作(因为当前使用的是 instanceof
检查)。
¥You need to make sure that ajv-formats imports the same version and the same code of ajv as the one you use in your application for standalone validation code to work (because of instanceof
check that is currently used).
当你在应用中更新 ajv 版本时,npm
和其他包管理器可能不会更新 ajv 格式的 ajv 依赖的版本 - 解决方法是使用干净的 npm 安装。
¥npm
and other package managers may not update the version of ajv dependency of ajv-formats when you update version of ajv in your application - the workaround is to use clean npm installation.
如果你定义自己的格式,为了使独立代码生成正常工作,你需要将计算结果为具有所有定义格式的对象的代码片段传递给选项 code.formats
:
¥If you define your own formats, for standalone code generation to work you need to pass the code snippet that evaluates to an object with all defined formats to the option code.formats
: