How to override an object array property type in RAML 1.0

Question

I have a generic Java type like this:

class Response<D> {
  List<D> data;
}

and want to create something similar with RAML 1.0 (where I am new to).

My first approach was

types:
  Response:
    type: object
    properties:
      data: object[]

and when using it

body:
  type: Response
    properties:
      data: MyDataType[]

From API-Workbench I always get an "Illegal override of property data inherited from Response".

The other idea would be to use repeat:

types:
  Response:
    type: object
    properties:
      data: object
      repeat: true

and respectively

body:
  type: Response
    properties:
      data: MyDataType
      repeat: true

Now the illegal override is gone but in the API-Console I now get an "Uncaught TypeError".

How to solve that? Or do I need a completely different approach? Any idea?

Kerns

Answer 1

As I understand, Response is abstracting different types of data, but has similar format. One approach is to abstract the similarity in the response using resourceTypes and define your concrete data in types.

#%RAML 1.0
title: New API
version: v1
baseUri: http://api.samplehost.com
mediaType: application/json

types:
  User:
    usage: A user in the system    
    properties:
      firstname:
        required: true
      lastname:
        required: true

  ArticleId:
    usage: An id of any article in the system
    type: number

  Article:
    usage: Pattern for any article in the system
    properties:
      id:
        type: ArticleId
        required: true
      created:
        type: date
        required: true

#######################################
# the following captures the similarity:
#######################################

resourceTypes:
  collection:
    get:
      responses:
        200:
          body:
            properties:
              data: <<typename>>[]


###############
# API:
############### 

/user:
  description: All the users
  type:
    collection:
      typename: User

/article:
  description: All the articles
  type:
    collection:
      typename: Article     

Apery

Answer 2

I see the following options in solving this issue:

1. Screen open source repositories for testcases, which hopefully document your requirements. I found this project raml-java-parser tests with a load of testcases but couldn't find the solution on the first try. Here is a specific testcase resource containing the string collectionSchema in double angle brackets (from raml-for-jaxrs) syntax, looks suspicous?
2. Use an API to produce a serialized version of the expected input e.g. your List<MyDataType>, and revise the generated output. E.g. using the same raml-java-parser from point 1.
3. Find a reference for the whole file specification, including complex types. Seems as this and this could include the interesting information, like "map/dictionary with type{} or the fact that exterior types might need an inclusion. Maybe this answer link helps on this behalf.
4. The raml tag on your question is currently followed by only 37 users. Are there more general tags possible, in order target a broader audience?

I didn't knew anything about RAML 20 minutes ago, so don't treat this as a complete answer but a quick guess.

Derisible

Answer 3

You said "and when using it": body: type: Response properties: data: MyDataType[]

You already defined the "Response" type above to have a "data" property as "object[]". Where did "MyDataType" come from? Just remove "properties" here and just have "type: Response. Then the error should go away.
Perhaps you are wanting your Response type to have "any[]". I cannot tell what you are trying to do. Maybe define another type which inherits your Response type.

Pathic

Maybe you missed the Java type declaration and the mentioned generic in the question but any would remove the error but document nothing, which is not the intention of using a endpoint documentation tool. – Kerns