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
npm install -g ramldt2jsonschema
This will install two command-line tools:
dt2js
: RAML data type <> JSON schemajs2dt
: JSON schema <> RAML data type
dt2js:
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:
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:
{
"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:
{
"$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:
#%RAML 1.0 Library
types
PingResponse
type object
additionalPropertiestrue
properties
status
type string
requiredtrue
apiName
type string
requiredfalse
apiVersion
enum
v1
v2
type string
requiredtrue
timestamp
type datetime
requiredtrue
dependencies
(amf-tuple)true
requiredtrue
Example 2
Sample JSON input:
{
"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:
{
"$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:
#%RAML 1.0 Library
types
WordPress
type object
additionalPropertiestrue
properties
id
type integer
requiredtrue
date
type string
requiredtrue
date_gmt
type string
requiredtrue
guid
type object
additionalPropertiestrue
properties
rendered
type string
requiredtrue
requiredtrue
modified
type string
requiredtrue
modified_gmt
type string
requiredtrue
slug
type string
requiredtrue
status
type string
requiredtrue
type
type string
requiredtrue
link
type string
requiredtrue
title
type object
additionalPropertiestrue
properties
rendered
type string
requiredtrue
requiredtrue
content
type object
additionalPropertiestrue
properties
rendered
type string
requiredtrue
requiredtrue
excerpt
type object
additionalPropertiestrue
properties
rendered
type string
requiredtrue
requiredtrue
author
type integer
requiredtrue
featured_media
type integer
requiredtrue
comment_status
type string
requiredtrue
ping_status
type string
requiredtrue
sticky
type boolean
requiredtrue
template
type string
requiredtrue
format
type string
requiredtrue
meta
type array
items
type any
requiredtrue
categories
(amf-tuple)true
requiredtrue
tags
(amf-tuple)true
requiredtrue
Limitations:
- Arrays are not converted to individual records/items, they are shown as amf-tuple
Opinions expressed by DZone contributors are their own.
Comments