How to Convert JSON to RAML

From JSON to schema to RAML!

Ashish Shrivastava

Jun. 05, 22 · Integration Zone · Tutorial

Like (1)

Save

3.93K Views

While working on creating API specifications using RAML, many times, we need to create a RAML Library or DataType from JSON payloads. We can accomplish this manually by using an API modeling tool like MuleSoft Anypoint Design Center. However, if the JSON payload is very large with multiple attributes, the conversion task becomes time-consuming and error-prone. It is better to use a tool that helps automate the conversion. ramldt2jsonschema is one such tool. It is a CLI and library for converting a RAML 1.0 DataType to a JSON schema, and back. It uses webapi-parser under the hood.

The conversion process can be split into three steps.

Convert JSON file to JSON Schema – We can use any free online JSON to JSON schema converter for this purpose. Some of these, like JSON-Formatter and Code-Beautify, convert JSON to draft-06 version of JSON schema, whereas others, like JSON-to-Schema-Converter, convert JSON to the draft-04 version of a JSON schema (version 07 is the latest).
Modify JSON Schema fields as required – If some of the fields need to be made optional or a particular field range with maximum/minimum values needs to be applied, that can be done in the converted JSON schema.
Convert JSON Schema to RAML Library – In this step, the JSON schema is converted to RAML library using ramldt2jsonschema CLI as shown in the examples below.

ramldt2jsonschema Usage

Installation

     Shell 
   
   npm install -g ramldt2jsonschema

This will install two command-line tools:

dt2js: RAML data type <> JSON schema
js2dt: JSON schema <> RAML data type

dt2js:

     Shell 
   
   dt2js <ramlFile> <ramlTypeName> --draft=[version] [--validate]

Options

<ramlFile>: Path to a file containing at least one RAML data type (e.g. path/to/api.raml)
<ramlTypeName>: RAML type name to convert to JSON schema
--draft: Optional JSON Schema draft version to convert to. Supported values are: 04, 06 and 07
--validate: Validate output JSON Schema with Ajv. Throws an error if the schema is invalid. Requires "ajv" to be installed. (default: false)

js2dt:

     Shell 
   
   js2dt <jsonFile> <ramlTypeName> [--validate]

Options:

<jsonFile>: Path to a JSON schema file (e.g. path/to/schema.json)
<ramlTypeName>: RAML type name to give to the exported RAML data type
--validate: Validate output RAML with webapi-parser. Throws an error if it is invalid. (default: false)

Example 1

Sample JSON Input:

     JSON 
   
 
 
   {
	"status": "OK",
    "apiName": "salesforce-sys-api",
    "apiVersion": "1.3.0",
    "timestamp": "2020-08-01T13:15:25.000Z",
    "dependencies": [
        {
            "name": "Salesforce",
            "status": "UP"
        }
    ]
} 
  

Converted JSON schema:

     JSON 
   
 
 
   {
  "$schema": "http://json-schema.org/draft-04/schema#",  
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "apiName": {
      "type": "string",
      "required": false //modified
    },
    "apiVersion": {
      "type": "string",
      "enum": ["v1","v2"]  //modified
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"  //modified              
    },
    "dependencies": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "status": {
              "type": "string"
            }
          },
          "required": [
            "name",
            "status"
          ]
        }
      ]
    }
  },
  "required": [
    "status",
    "apiName",
    "apiVersion",
    "timestamp",
    "dependencies"
  ]
} 
  

JSON Schema to RAML Library Conversion:

     YAML 
   
 
 
   #%RAML 1.0 Library
types:
  PingResponse:
    type: object
    additionalProperties: true
    properties:
      status:
        type: string
        required: true
      apiName:
        type: string
        required: false
      apiVersion:
        enum:
          - v1
          - v2
        type: string
        required: true
      timestamp:
        type: datetime
        required: true
      dependencies:
        (amf-tuple): true
        required: true 
  

Example 2

Sample JSON input:

     JSON 
   
 
 
   {
      "id": 157538,
      "date": "2017-07-21T10:30:34",
      "date_gmt": "2017-07-21T17:30:34",
      "guid": {
          "rendered": "https://www.sitepoint.com/?p=157538"
      },
      "modified": "2017-07-23T21:56:35",
      "modified_gmt": "2017-07-24T04:56:35",
      "slug": "why-the-iot-threatens-your-wordpress-site-and-how-to-fix-it",
      "status": "publish",
      "type": "post",
      "link": "https://www.sitepoint.com/why-the-iot-threatens-your-wordpress-site-and-how-to-fix-it/",
      "title": {
          "rendered": "Why the IoT Threatens Your WordPress Site (and How to Fix It)"
      },
      "content": {
          "rendered": "XYZ"
      },
      "excerpt": {
          "rendered": "ABC"
      },
      "author": 72546,
      "featured_media": 157542,
      "comment_status": "open",
      "ping_status": "closed",
      "sticky": false,
      "template": "",
      "format": "standard",
      "meta": [],
      "categories": [
          6132
      ],
      "tags": [
          1798,
          6298
      ],
} 
  

Converted JSON schema:

     JSON 
   
 
 
   {
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "date": {
      "type": "string"
    },
    "date_gmt": {
      "type": "string"
    },
    "guid": {
      "type": "object",
      "properties": {
        "rendered": {
          "type": "string"
        }
      },
      "required": [
        "rendered"
      ]
    },
    "modified": {
      "type": "string"
    },
    "modified_gmt": {
      "type": "string"
    },
    "slug": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "link": {
      "type": "string"
    },
     "title": {
      "type": "object",
      "properties": {
        "rendered": {
          "type": "string"
        }
      },
      "required": [
        "rendered"
      ]
    },
    "content": {
      "type": "object",
      "properties": {
        "rendered": {
          "type": "string"
        }
      },
      "required": [
        "rendered"
      ]
    },
    "excerpt": {
      "type": "object",
      "properties": {
        "rendered": {
          "type": "string"
        }
      },
      "required": [
        "rendered"
      ]
    },
    "author": {
      "type": "integer"
    },
    "featured_media": {
      "type": "integer"
    },
    "comment_status": {
      "type": "string"
    },
    "ping_status": {
      "type": "string"
    },
    "sticky": {
      "type": "boolean"
    },
    "template": {
      "type": "string"
    },
    "format": {
      "type": "string"
    },
    "meta": {
      "type": "array",
      "items": {}
    },
    "categories": {
      "type": "array",
      "items": [
        {
          "type": "integer"
        }
      ]
    },
    "tags": {
      "type": "array",
      "items": [
        {
          "type": "integer"
        },
        {
          "type": "integer"
        }
      ]
    }
  },
  "required": [
    "id",
    "date",
    "date_gmt",
    "guid",
    "modified",
    "modified_gmt",
    "slug",
    "status",
    "type",
    "link",
    "title",
    "content",
    "excerpt",
    "author",
    "featured_media",
    "comment_status",
    "ping_status",
    "sticky",
    "template",
    "format",
    "meta",
    "categories",
    "tags"
  ]
} 
  

JSON schema to RAML library conversion:

     YAML 
   
 
 
   #%RAML 1.0 Library
types:
  WordPress:
    type: object
    additionalProperties: true
    properties:
      id:
        type: integer
        required: true
      date:
        type: string
        required: true
      date_gmt:
        type: string
        required: true
      guid:
        type: object
        additionalProperties: true
        properties:
          rendered:
            type: string
            required: true
        required: true
      modified:
        type: string
        required: true
      modified_gmt:
        type: string
        required: true
      slug:
        type: string
        required: true
      status:
        type: string
        required: true
      type:
        type: string
        required: true
      link:
        type: string
        required: true
      title:
        type: object
        additionalProperties: true
        properties:
           rendered:
            type: string
            required: true
        required: true
      content:
        type: object
        additionalProperties: true
        properties:
          rendered:
            type: string
            required: true
        required: true
      excerpt:
        type: object
        additionalProperties: true
        properties:
          rendered:
            type: string
            required: true
        required: true
      author:
        type: integer
        required: true
      featured_media:
        type: integer
        required: true
      comment_status:
        type: string
        required: true
      ping_status:
        type: string
        required: true
      sticky:
        type: boolean
        required: true
      template:
        type: string
        required: true
      format:
        type: string
        required: true
      meta:
        type: array
        items:
          type: any
        required: true
      categories:
        (amf-tuple): true
        required: true
      tags:
        (amf-tuple): true
        required: true 
  

Limitations:

Arrays are not converted to individual records/items, they are shown as amf-tuple

JSON Convert (command) Schema

Opinions expressed by DZone contributors are their own.

Comments