Nav

Support for RAML 1.0 Data Types in Datasense

Datasense now supports RAML 1.0 data types, and can parse this information to be displayed in the DataSense explorer.

RAML 1.0 Data Types

RAML v1.0 introduced Data Types, a concise and versatile way to describe and validate data inside your API definition.
You can define a type at the beginning of your RAML file, and you can later reference that same type to describe the body of as many API requests or responses as you need. You can even define a data type to inherit properties of another type within your API.
Think of data types as a define once, use many schema-like definition.

Datasense now supports data types inheritance along with XML and JSON schema propagation across your RAML 1.0 API description, allowing the Datasense explorer to correctly display the metadata generated by your RAML file including fields and types inherited from your type declarations.

Example

Consider a simple example of an API that serves and populates resources with contact information from two different types of contacts: companies and individuals.
Using Data Types, you can define a contact type, with properties address and email information. You can also define specific properties for each contact information property.
In RAML 1.0 it would look like this:


         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
#%RAML 1.0

title: Contact Information API
mediaType: application/json

types:

  ###############
  # Contacts Data:
  ###############

  Contact:
   properties:
     address:
       type: Address
     email:
       type: Email

  Address:
    properties:
      street:
        type: string
      city:
        type: string
      state:
        type: string
      country:
        type: string

  Email:
    pattern: ^[_a-z0-9-]+(\.[_a-z0-9-]+)*@[a-z0-9-]+(\.[a-z0-9-]+)*(\.[a-z]{2,4})$

Now you can define individuals and companies leveraging their contact-information property in the data types defined earlier:


         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
###############
# Contacts:
###############

Individual:
  properties:
    name:
      type: string
    contact-information:
      type: Contact

Company:
  properties:
    company-name:
      type: string
    contact-information:
      type: Contact

Finally, for the API definition, you can define get and post methods for both resources (`/individuals`and `/companies):


         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
###############
# API:
###############

/individuals:
  get:
    responses:
      200:
        body:
          type: Individual
          example: |
              {
                "name": "Max",
                "contact-information": {
                  "address": {
                    "street":"Market Street",
                    "city":"San Francisco",
                    "state":"California",
                    "country":"United States"
                    },
                  "email":"max@mail.com"
                 }
              }
  post:
    body:
        type: Individual
    responses:
      200:
        body:
          example: |
              {
                "name":"",
                "contact-information": {
                  "address": {
                    "street":"",
                    "city":"",
                    "state":"",
                    "country":""
                   },
                 "email": ""
                }
              }

/companies:
  get:
    body:
      type: Company
    responses:
      200:
        body:
          type: Company
          example: |
             {
                "company-name": "MuleSoft",
                "contact-information": {
                  "address": {
                    "street":"77 Geary St.",
                    "city":"San Francisco",
                    "state":"California",
                    "country":"United States"
                    },
                  "email":"mulesoft@mail.com"
                 }
              }
  post:
   body:
    type: Company
   responses:
    200:
      body:
        example: |
              {
                "company-name": "",
                "contact-information": {
                  "address": {
                    "street":"",
                    "city":"",
                    "state":"",
                    "country":""
                    },
                  "email":""
                 }
              }

If you download this RAML definition example, import it into Studio, add logger processor at any of the generated flows and inspect the input displayed by the DatasSnse explorer, you can see the metadata populated considering al the types definition and inheritance.

This is how it looks when inspecting the GET method for the /companies resource:

raml-1-0-data-types-support-8cf05

DataSense even recognizes if you change the API’s mediaType to application/xml:

raml 1 0 data types support 4e17d

Datasense can even handle xml attribute type declarations. Such as:


         
      
1
2
3
4
5
6
7
8
9
Company:
  properties:
    company-name:
      type: string
      xml:
        attribute: true
        name: xmlname
    contact-information:
      type: Contact
raml 1 0 data types support b4cb0