ramldt2jsonschema
CLI & Library to convert a RAML 1.0 DataType to a JSON Schema Draft 4, 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 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 Shema draft version to convert to. Supported values are:04
,06
and07
(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 = const join = joinconst fs = const filePath = const ramlData = fs { let schema try schema = await r2j catch err console return console}
js2dt
const r2j = const join = joinconst fs = const yaml = const filePath = const jsonData = fs { let raml try raml = await r2j catch err console return console console}
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.jsonconst raml2json = const ramlStr = ` #%RAML 1.0 Library types: Person: !include simple_person.json`const basePath = '/home/john/schemas/' // or '../../schemas/'const schema = raml2jsonconsole
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)
- the following JSON Schema properties are not supported and as a result, may not be converted as expected:
License
Apache 2.0