RAML: Nested Schemas

Question

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

For example:

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 a choices/enum around a set of nestable schemas?

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

Answer 1

1) Yes, you can. See this example. That would be:

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

2) I believe this is possible in Draft 4 of JSON Schema, using the oneOf directive. I don't think this is supported by RAML though. Alternatively, you could create a base schema and have ARecord, MXRecord and PTRRecord extend this base schema and then allow items of the base schema. This won't be very semantically rich but could get you started.

Answer 2

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

With the release of the RAML 1.0 specifications, you can use types, which allows you to do just that (in what I consider slightly cleaner).

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

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

And for those that want less text and more examples (taken from 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 the following example applies here. It demonstrates defining two types Url and File (using RAML 1.0) and then using the logical OR to allow either type (aka schema) in Item as a subschema. You could potentially include more types if needed.

I also defined some examples inline which demonstrate how it works if you are using the 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