Define type and example in RAML 1.0


#1

I have the following in my RAML 0.8 but I can’t convert it to RAML 1.0. Could somebody give me some help?

Here is part of my code:

schemas:
  - type1: |
      {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "title": "Type",
        "type": "object",
        "properties": {
          "id": {
              "description": "descr",
              "type": "string"
          },
          "metadata": {
              "description": "descr",
              "type": "object",
              "properties": {
                "property1": {
                  "type": "string",
                  "description": "descr"
                },
                "property2": {
                  "type": "string",
                  "description": "descr"
               }
              }
          },
          "exception": {
            "type": "object",
            "description": "descr",
            "properties": {
              "property1": {
              "description": "descr.",
              "type": "string"
              },
              "property2": {
                  "description": "descr",
                  "type": "string"
              },
              "property2": {
                  "type": "array",
                  "description": "descr",
                  "items": {
                    "type": "string"
                  }
              }
            }
          }
        },
        "required": ["property1", "property2", "property3"]
      }

    responses:
          200:
            description: OK
            body:
              application/json:
                schema: |
                  {
                      "$schema": "http://json-schema.org/draft-04/schema#",
                      "title": "Exceptions",
                      "type": "array",
                      "items": { "$ref": "type1" }
                  }
                example: |
                  {
                    "request": {
                      "property1": "some value",
                      "property"2: "some value"
                    },
                    "response": {
                      "property1": "some value",
                      "property"2: "some value"
                    },
                    "results": [
                      {
                        "id": "myId",
                        "metadata": {
                          "property1": "some value",
                          "property2": "some value"
                        },
                        "type1": {
                          "property1": "some value",
                          "property2": "some value",
                          "property3": [
                             "first.line",
                             "	second.line",
                             "	................. ",
                             "	last.line"
                            ]
                          }
                      },
                      {
                        "id": "myId",
                        "metadata": {
                          "property1": "some value",
                          "property2": "some value"
                        },
                        "type1": {
                          "property1": "some value",
                          "property2": "some value",
                          "property3": [
                             "first.line",
                             "	second.line",
                             "	................. ",
                             "	last.line"
                            ]
                          }
                      }
                    ]
                  }

#2

Hi,

Your schema does not look valid or very coherent and you might be better off mapping your types and resources based on the needs of your API, instead of trying to translate your json-schemas.

I gave it a try, hope this helps you a bit.

Your type seems to look like this:

types:
  type1:
    type: object
    properties:
      id:
        type: string
        required: false
        description: This describes id, but you do not have to
      metadata:
        properties:
          property1: string
          property2: string
      exception:
        properties:
          property1: string
          property2: string
          property3: string[]

Your resource can implement the type:

/yourmissingresourcename:
  get:
    responses:
      200:
        application/json:
          type: type1
          example: 
            type1:
              id: stringidexample
              metatdata:
                property1: thisIstext
                property2: thisIsmoretext
              exception:
                property1: againSomeSimpleText
                property2: textext
                property3: [text, again, helloworld]

An example of the JSON you would return:

{
  "type1": {
      "id": "theIdasAstring",
      "metadata": {
          "property1": "text",
          "property2": "text"
        },
        "exception": {
            "property1": "aString",
            "property2": "anotherString",
            "property3": [
              "textone",
              "texttwo",
              "textthree"
            ]
          }
    }
}

But again, this is not the best way in my opinion. Another option is reading the RAML spec thoroughly on github and the tutorials, checking out the raml-examples on github and using an IDE with validation, such as Atom with API-workbench.
Good luck!


#3

(reformatted your text for readability)

@asdf1515: you may want to use an Array type to model your response. You can find some examples on the RAML 1.0 spec.