How to Convert JSON to RAML
From JSON to schema to RAML!
Join the DZone community and get the full member experience.
Join For FreeWhile 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 ramldt2jsonschemaThis will install two command-line tools:
dt2js: RAML data type <> JSON schemajs2dt: 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: trueExample 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: trueLimitations:
- 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