Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
bin
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

ramldt2jsonschema

Greenkeeper badge NPM version NPM downloads Build status Test coverage

CLI & Library to convert a RAML 1.0 DataType to a JSON Schema, and back. Uses webapi-parser under the hood.

Usage

Global (CLI)

npm install -g ramldt2jsonschema

This will install two command-line tools:

  • dt2js: RAML data type <> JSON schema
  • js2dt: 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 Shema draft version to convert to. Supported values are: 04, 06 and 07 (default)
  • --validate Validate output JSON Schema with Ajv. Throws an error if 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)

Locally (JavaScript)

npm install ramldt2jsonschema --save

dt2js

const r2j = require('ramldt2jsonschema')
const join = require('path').join
const fs = require('fs')

const filePath = join(__dirname, 'complex_cat.raml')
const ramlData = fs.readFileSync(filePath).toString()

async function main () {
  let schema
  try {
    schema = await r2j.dt2js(ramlData, 'Cat')
  } catch (err) {
    console.log(err)
    return
  }
  console.log(JSON.stringify(schema, null, 2))
}

main()

js2dt

const r2j = require('ramldt2jsonschema')
const join = require('path').join
const fs = require('fs')
const yaml = require('js-yaml')

const filePath = join(__dirname, 'complex_cat.json')
const jsonData = fs.readFileSync(filePath).toString()

async function main () {
  let raml
  try {
    raml = await r2j.js2dt(jsonData, 'Cat')
  } catch (err) {
    console.log(err)
    return
  }
  console.log('#%RAML 1.0 Library\n')
  console.log(yaml.safeDump(raml, { 'noRefs': true }))
}

main()

Resolving references

When the input contains external references (!include, uses:, $ref, etc.) and the referred files are not in the same directory as the script it is being ran from, you may provide a third argument to both dt2js and js2dt. The argument must be an object with a basePath key. All references will then be resolved relative to that base path.

Example of using basePath argument in dt2js:

// Script below ran from /home/john/where/ever/
// Reference is located at /home/john/schemas/simple_person.json
const raml2json = require('ramldt2jsonschema')

const ramlStr = `
  #%RAML 1.0 Library

  types:
    Person: !include simple_person.json
`
const basePath = '/home/john/schemas/' // or '../../schemas/'
const schema = raml2json.dt2js(ramlStr, 'Person', { basePath: basePath })
console.log(JSON.stringify(schema, null, 2))

Limitations

  • in js2dt
    • the following JSON Schema properties are not supported and as a result, may not be converted as expected:

      dependencies, exclusiveMaximum, exclusiveMinimum, items (array value), allOf, oneOf, not, format (email, hostname, ipv4, ipv6, uri), readOnly

    • the following JSON Schema properties won't be converted at all:

      $schema, additionalItems, contains, id, $id, propertyNames, definitions, links, fragmentResolution, media, pathStart, targetSchema

    • array items property is not properly converted to RAML when it's value is an array of schemas (see #111)

License

Apache 2.0

You can’t perform that action at this time.