RAML: nested schemas

Question

1) When writing RAML, can I use nesting in my schema definition?

For instance:

schemas: - DNSResponse: | { "type": "object", "properties": { "AnswerSection": { "type": "array", "items": (((I want a re-useable schema here. ex: ARecord))) }, "AA": {"type": "boolean"}, "AD": {"type": "boolean"}, ... } } - ARecord: | { "type": "object", "properties": { "address": "string", "ttl": "number", "name": "string" } } 

2) Can I use selection / enumeration around a set of nesting schemes?

 "items": [ARecord, MXRecord, PTRRecord, ...] 

Answer 1

1) Yes, you can. See this example . It will be:

 "items": { "$ref": "ARecord" } 

2) I believe that this is possible in project 4 JSON schemes using the oneOf directive. I do not think this is supported by RAML. In addition, you can create a base schema and ARecord, MXRecord, and PTRRecord extend this base schema and then enable the elements of the base schema. It will not be very semantically rich, but you can start.

Answer 2

Since your question is not 100% JSON required, I will add this to the answers ...

With the release of the RAML 1.0 specs, you can use types , which allows you to do just that (in which I find it a little cleaner).

Here is the link: http://docs.raml.org/specs/1.0/#raml-10-spec-types

RAML 1.0 introduces the concept of data types, which provide a concise and powerful way to describe data in your API. The data can be in the URI parameter (base or resource URI), the request parameter, the request or response header, or, of course, the body of the request or response. Some types are built-in, and custom types can be defined by extending (inheriting) built-in types. Wherever the API expects data, a built-in type can be used to describe the data, or the type can be extended by a built-in type to describe this data. CustomSecurityScheme types can also be named and then used like any built-in type.

And for those who want less text and more examples (taken from the RAML documentation):

 #%RAML 1.0 title: API with Types types: User: type: object properties: firstname: string lastname: string age: number /users/{id}: get: responses: 200: body: application/json: type: User 

Answer 3

I think an example is given here. It demonstrates the definition of two types, Url and File (using RAML 1.0), and then using a logical OR to resolve any type (aka schema) in Item as a subcircuit. If necessary, you can include more types in it.

I also defined a series of examples that demonstrate how this works if you use raml-parser.

 #%RAML 1.0 types: Url: properties: url: type: string example: http://www.cats.com/kittens.jpg description: | The url to ingest. File: properties: filename: type: string example: kittens.jpg description: | Name of the file that will be uploaded. Item: description: | An example of a allowing multiple types using RAML 1.0 properties: ext: type: File | Url examples: file_example: content: ext: filename: video.mp4 url_example: content: ext: url: http://heres.a.url.com/asset.jpg should_fail: content: ext: unexpected: blah