RAML 0.8中引用JSON Schema的方法详解

在RAML 0.8的规范中，以Schema的方式定义资源Resources。

为了能够引用JSON Schema，提供了两个关键字schemas和schema。schemas用以声明资源，而schema用以引用资源。

根据是否在raml文件中定义JSON Schema，引用JSON Schema有两种方式，一种是在raml文件中引用独立的JSON Schema文件，另一种是在raml文件中直接使用JSON Schema片段。
1.使用schemas声明资源

...schemas:  - User:  schema/user.json    Users: schema/users.json    Org:   schema/org.json    Orgs:  schema/orgs.json...

或

...schemas:  - !include path-to-canonical-schemas/canonicalSchemas.raml  - File:       !include path-to-schemas/filesystem/file.xsd    FileUpdate: !include path-to-schemas/filesystem/fileupdate.xsd    Files:      !include path-to-schemas/filesystem/files.xsd    Dir:        !include path-to-schemas/filesystem/dir.xsd    Dirs:       !include path-to-schemas/filesystem/dirs.xsd...

2.使用schema引用资源

1) 对于已经声明过的资源，可以在后续raml文件中直接引用

/files:  get:    responses:      200:        body:          application/xml:            schema: Files

2) 也可以引用从未声明过的资源

/jobs:  displayName: Jobs  post:    description: Create a Job    body:      text/xml:        schema: !include job.xsd      application/json:        schema: !include job.schema.json

或

/jobs:  displayName: Jobs  post:    description: Create a Job    body:      text/xml:        schema: |          <xs:schema attributeFormDefault="unqualified"                     elementFormDefault="qualified"                     xmlns:xs="http://www.w3.org/2001/XMLSchema">            <xs:element name="api-request">              <xs:complexType>                <xs:sequence>                  <xs:element type="xs:string" name="input"/>                </xs:sequence>              </xs:complexType>            </xs:element>          </xs:schema>      application/json:        schema: |          {            "$schema": "http://json-schema.org/draft-03/schema",            "properties": {                "input": {                    "required": false,                    "type": "string"                }            },            "required": false,            "type": "object"          }

注意，对于application/x-www-form-urlencoded或multipart/form-data时，不能使用schema。

3. 补充：与schema类似，RAML 0.8中还提供了example，可以引用JSON Schema。

      application/json:        schema: !include job.schema.json        example: |          {            "input": "s3://zencodertesting/test.mov"          }

或

      application/json:        example: !include examples/instagram-v1-media-popular-example.json

参考链接：

https://github.com/raml-org/raml-spec/blob/master/versions/raml-08/raml-08.md