JSON Schema

什么是JSON SchemaJSON Schema就是给 JSON 数据写的一份“标准说明书”可以认为JSON Schema就是json模板。对于agent来说有了JSON Schema才能进行数据交换。注在agent开发中JSON 对象通常被称为Function Schema或Tool Definition的主要作用是告诉 LLM“如果你想调用...的工具你必须按照这个格式给我发送参数。”JSON Schema 规范JSON Schema 的基础是type关键字。它的作用是规定 JSON 数据中某个字段必须属于哪种“数据类型”。下表是json数据类型与python数据类型的对应关系JSONPythonstringstring [4]numberint/float [5]objectdictarraylistbooleanboolnullNoneString字符串{ type: string }这段代码表明这个字段的值必须是一个字符串可以是文本字符串、空字符串但不能是字典、数字等其他类型。长度{ type: string, minLength: 2, maxLength: 3 }可以使用minLength和maxLength关键字来限制字符串的长度除此之外还可以用正则表达式对字符串进行约束本章对此不进行详细赘述。integer/number数字JSON Schema 中有两种数字类型integer和number。它们共享相同的验证关键字integer{ type: integer }integer类型用于整数。JSON 没有针对整数和浮点值的不同类型。因此有无小数点并不足以区分整数和非整数。例如1和1.0是在 JSON 中表示相同值的两种方式。无论使用哪种表示形式JSON 模式都将该值视为整数。这个字段可以接收整数和小数部分为0的数但不能是字符串、浮点数等。number{ type: number }number类型用于任何数字类型整数或浮点数可以接收整数、浮点数、带指数符号的数但不能接受作为字符串的数字。倍数{ type: number, multipleOf : 10 }以使用multipleOf关键字将数字限制为给定数字的倍数 。它可以设置为任何正数该字段必须是10的倍数。范围使用minimum和maximum或exclusiveMinimum和exclusiveMaximum可以规定数字的取值范围。如果x是要验证的值则以下必须成立x≥minimumxexclusiveMinimumx≤maximumxexclusiveMaximum示例{ type: number, minimum: 0, exclusiveMaximum: 100 }Object对象对象是 JSON 中的映射类型。他们将“键”映射到“值”。在 JSON 中“键”必须始终是字符串。这些对中的每一组通常被称为“属性”。注意在 Python 中“对象”类似于dict类型。然而一个重要的区别是虽然 Python 字典可以使用任何可散列的键作为键但在 JSON 中所有键都必须是字符串。尽量不要被此处“对象”一词的两种用法所混淆Python 使用该词object来表示所有事物的通用基类而在 JSON 中它仅用于表示从字符串键到值的映射。{ type: object } { key: value, another_key: another_value }该字段可以是如图所示的字典但是不接受使用非字符串作为键、以及列表等其他数据类型。属性对象的属性键值对是使用properties关键字定义的 。properties的值是一个对象其中每个键是属性的名称每个值是用于验证该属性的模式。此properties关键字将忽略与关键字中的任何属性名称不匹配的任何属性。例如我们要为由数字、街道名称和街道类型组成的地址定义一个简单的模式{ type: object, properties: { number: { type: number }, street_name: { type: string }, street_type: { enum: [Street, Avenue, Boulevard] } } } // OK { number: 1600, street_name: Pennsylvania, street_type: Avenue } // not OK提供的号码类型错误则无效 { number: 1600, street_name: Pennsylvania, street_type: Avenue } // OK默认情况下省略属性是有效的。请参阅必需属性。 { number: 1600, street_name: Pennsylvania } // OK通过扩展即使是空对象也是有效的 { } // OK默认情况下提供附加属性是有效的 { number: 1600, street_name: Pennsylvania, street_type: Avenue, direction: NW }必须属性在 JSON Schema 中required关键字的作用是规定哪些字段是必须存在的该required关键字采用零个或多个字符串的数组。这些字符串中的每一个都必须是唯一的{ type: object, properties: { name: { type: string }, email: { type: string }, address: { type: string }, telephone: { type: string } }, required: [name, email] } // OK { name: William Shakespeare, email: billstratford-upon-avon.co.uk } // OK提供额外的属性是可以的即使是架构中没有定义的属性 { name: William Shakespeare, email: billstratford-upon-avon.co.uk, address: Henley Street, Stratford-upon-Avon, Warwickshire, England, authorship: in question }array数组在 JSON 中数组中的每个元素可能是不同的类型{ type: array } [1, 2, 3, 4, 5] // OK [3, different, { types : of values }] // OK {Not: an array} // not OK元素验证JSON 中数组的使用一般有两种方式列表验证任意长度的序列其中每个项目都匹配相同的模式。关注的是数组作为一个整体的特征元组验证一个固定长度的序列其中每个项目可能有不同的模式。关注的是数组里装的是什么列表验证如果你希望数组里的所有元素都遵循同一种规则就给items传入一个 Schema 对象{ type: array, items: { type: number } } [1, 2, 3, 4, 5] // OK [1, 2, 3, 4, 5] // not OK单个“非数字”会导致整个数组无效 [] // OK空数组始终有效元组验证如果你希望数组的第 1 位是字符串第 2 位是数字位置固定这叫“元组”验证{ type: array, items: [ { type: number }, { type: string }, { enum: [Street, Avenue, Boulevard] }, { enum: [NW, NE, SW, SE] } ] } [1600, Pennsylvania, Avenue, NW] // OK [24, Sussex, Drive] // not OK“Drive”不是可接受的街道类型之一 [Palais de lÉlysée] // not OK此地址缺少街道号码 [10, Downing, Street] // OK可以不提供所有项目长度可以使用minItems和maxItems关键字指定数组的长度。每个关键字的值必须是非负数。无论是进行List 验证还是Tuple 验证这些关键字都 有效。{ type: array, minItems: 2, maxItems: 3 } [] // not OK [1] // not OK [1, 2] // OK [1, 2, 3] // OK [1, 2, 3, 4] // not OK唯一性只需将uniqueItems关键字设置为true可以限制数组中的每个元素都是唯一的{ type: array, uniqueItems: true } [1, 2, 3, 4, 5] // OK [1, 2, 3, 3, 4] // not OKMetadata关键字Metadata通用注释关键词并不严格用于验证而是用于描述模式的一部分。这些“注释”关键字都不是必需的但鼓励使用为了良好实践并且可以使您的模式“自我记录”title用于给这个schema起一个名字{ title: 用户信息表单, // 根部元数据 type: object, properties: { age: { type: integer, description: 玩家的年龄 // 局部元数据 } } }注意title必须是字符串description用于详细描述这个字段的用途同样地description也必须是字符串。default用于规定默认值不强制校验但提示客户端如果没传值该填什么。{ title: Match anything, description: This is a schema that matches anything., default: Default value, examples: [ Anything, 4035 ], }enum用于将值限制为一组固定的值。它必须是一个包含至少一个元素的数组其中每个元素都是唯一的。{ enum: [red, amber, green] } red // OK blue // not OK