RAML 1.0中example与examples facet差异问题咨询（Mule 4培训场景）

核心原因 #

你遇到的问题本质是RAML 1.0对example和examples两个facet的校验逻辑不同：

• example是强校验绑定：它要求引用的示例内容严格匹配接口返回的类型定义。如果你的AmericanFlightExample.raml里的示例是数组格式，而这个GET/{ID}接口定义的返回是单个AmericanFlight对象，API Designer会判定示例结构不匹配，进而抛出“必填字段缺失”的错误（因为数组和单个对象的结构校验逻辑完全不同）。
• examples是弱校验展示：这个facet允许定义多个示例，校验逻辑宽松很多，不会强制要求示例严格贴合返回类型的结构约束，所以即使示例是数组格式，也不会触发校验错误。

你的理解没错，但示例结构不匹配 #

你认为单个实例该用example的逻辑完全正确——example就是用来定义单个返回实例的标准用法，examples才是对应多实例/数组场景的。问题出在你引用的AmericanFlightExample.raml的内容结构，和这个接口的返回类型不匹配。

解决方向 #

1. 检查AmericanFlightExample.raml的内容，确认它是单个AmericanFlight对象还是数组。如果是数组，把示例改成单个对象结构，再用example引用就不会报错。
2. 如果示例文件必须保留数组格式（比如要复用给其他返回数组的接口），那要么复制一份改成单个对象版本来引用，要么暂时用examples（但不推荐，因为会让文档示例和实际返回类型不一致）。

内容的提问来源于stack exchange，提问作者Nitin