DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Please enter at least three characters to search
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

Zones

Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

The software you build is only as secure as the code that powers it. Learn how malicious code creeps into your software supply chain.

Apache Cassandra combines the benefits of major NoSQL databases to support data management needs not covered by traditional RDBMS vendors.

Generative AI has transformed nearly every industry. How can you leverage GenAI to improve your productivity and efficiency?

Modernize your data layer. Learn how to design cloud-native database architectures to meet the evolving demands of AI and GenAI workloads.

Related

  • Exploring JSON Schema for Form Validation in Web Components
  • Datafaker Gen: Leveraging BigQuery Sink on Google Cloud Platform
  • Validate XML Request Against XML Schema in Mule 4
  • Validate JSON Request Against JSON Schema in Mule 4

Trending

  • AI Speaks for the World... But Whose Humanity Does It Learn From?
  • Orchestrating Microservices with Dapr: A Unified Approach
  • Enhancing Business Decision-Making Through Advanced Data Visualization Techniques
  • IoT and Cybersecurity: Addressing Data Privacy and Security Challenges
  1. DZone
  2. Coding
  3. Languages
  4. How to Convert JSON to RAML

How to Convert JSON to RAML

From JSON to schema to RAML!

By 
Ashish Shrivastava user avatar
Ashish Shrivastava
·
Jun. 05, 22 · Tutorial
Likes (1)
Comment
Save
Tweet
Share
11.6K Views

Join the DZone community and get the full member experience.

Join For Free

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.

  1. 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). 
  2. 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.
  3. 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:

  1. 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.

Related

  • Exploring JSON Schema for Form Validation in Web Components
  • Datafaker Gen: Leveraging BigQuery Sink on Google Cloud Platform
  • Validate XML Request Against XML Schema in Mule 4
  • Validate JSON Request Against JSON Schema in Mule 4

Partner Resources

×

Comments
Oops! Something Went Wrong

The likes didn't load as expected. Please refresh the page and try again.

ABOUT US

  • About DZone
  • Support and feedback
  • Community research
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Core Program
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • support@dzone.com

Let's be friends:

Likes
There are no likes...yet! 👀
Be the first to like this post!
It looks like you're not logged in.
Sign in to see who liked this post!