Merge pull request #105 from raml-org/develop

Migrate to webapi-parser to convert

.travis.yml

@@ -8,10 +8,10 @@ notifications:
 
 node_js:
   - "8"
-  - "lts/*"
+  - "10"
   - "node"
 
-script: npm run test-ci
+script: npm run test
 
 after_script: npm install coveralls@2 && cat ./coverage/lcov.info | coveralls
 

README.md

@@ -6,7 +6,7 @@
 [![Build status][travis-image]][travis-url]
 [![Test coverage][coveralls-image]][coveralls-url]
 
-CLI & Library to convert a RAML 1.0 DataType to a JSON Schema Draft 6, and back. (dt2js can still be used to produce draft04 documents if used programatically)
+CLI & Library to convert a RAML 1.0 DataType to a JSON Schema Draft 4, and back. Uses [webapi-parser](https://github.com/raml-org/webapi-parser) under the hood.
 
 ## Usage
 
@@ -23,13 +23,14 @@ This will install two command-line tools:
 #### dt2js
 
 ```
-dt2js <ramlFile> <ramlTypeName>
+dt2js <ramlFile> <ramlTypeName> --draft=[version]
 ```
 
 **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)
 
 #### js2dt
 
@@ -51,66 +52,82 @@ npm install ramldt2jsonschema --save
 #### dt2js
 
 ```js
-const raml2json = require('ramldt2jsonschema')
+const r2j = require('ramldt2jsonschema')
 const join = require('path').join
 const fs = require('fs')
 
-const filePath = join(__dirname, 'api.raml')
+const filePath = join(__dirname, 'complex_cat.raml')
 const ramlData = fs.readFileSync(filePath).toString()
 
-const schema = raml2json.dt2js(ramlData, 'Cat')
-console.log(JSON.stringify(schema, null, 2))
+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()
 ```
 
-NOTE: when the inputed RAML contains `!include`s and those includes are not in the same directory as the script it is being ran from, you can use `dt2js.setBasePath()` to specify a different base path.
+#### js2dt
 
 ```js
-const raml2json = require('ramldt2jsonschema')
+const r2j = require('ramldt2jsonschema')
 const join = require('path').join
 const fs = require('fs')
+const yaml = require('js-yaml')
 
-const filePath = join(__dirname, 'api.raml')
-const includesPath = '/different/path/to/includes/'
-const ramlData = fs.readFileSync(filePath).toString()
+const filePath = join(__dirname, 'complex_cat.json')
+const jsonData = fs.readFileSync(filePath).toString()
 
-raml2json.dt2js.setBasePath(includesPath)
-const schema = raml2json.dt2js(ramlData, 'Cat')
-console.log(JSON.stringify(schema, null, 2))
+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()
 ```
 
-#### js2dt
+#### 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:
 ```js
+// Script below ran from /home/john/where/ever/
+// Reference is located at /home/john/schemas/simple_person.json
 const raml2json = require('ramldt2jsonschema')
-const join = require('path').join
-const fs = require('fs')
 
-const filePath = join(__dirname, 'schema.json')
-const jsonData = fs.readFileSync(filePath).toString()
+const ramlStr = `
+  #%RAML 1.0 Library
 
-const raml = raml2json.js2dt(jsonData, 'Person')
-
-console.log(`#%RAML 1.0 Library\n${yaml.safeDump({ types: raml }, {'noRefs': true})}`)
+  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, will not be converted:
-    - `not` (or `false` when used as a schema boolean)
-    - object's `dependencies`
-    - array's `additionalItems`
-    - the `propertyNames` keyword
-    - the `contains` keyword
-  - JSON schema number and integer's `exclusiveMaximum` and `exclusiveMinimum` properties are converted to raml 'maximum' and 'minimum'
-  - the JSON schema `oneOf` property is processed the same way as the JSON schema `anyOf` property, it is converted to the RAML `union` type
-  - the JSON schema `type: 'string'` with `media` and `binaryEncoding: 'binary'` is converted to the RAML `file` type
-  - the JSON schema `type: string` with a `pattern` that matches exactly one of the RAML date types will be converted in the matching RAML date type
-  - the JSON schema `media` property with `anyOf`, elements of which have the property `mediaType` will be converted to `fileTypes` in RAML
-
-- in dt2js,
-  - the following RAML properties are not supported/converted:
-    - annotations
+- 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
+
 
 ## License
 

bin/dt2js.js

@@ -6,8 +6,13 @@ const cli = require('../src/dt2js_cli')
 
 program
   .arguments('<ramlFile> <ramlTypeName>')
+  .option(
+    '--draft <num>',
+    'JSON Shema draft version to convert to. Supported values are: "04", "06" and "07" (default)')
   .description('Convert a RAML data type into JSON schema. ' +
                'Writes to standard output.')
-  .action((f, t) => console.log(JSON.stringify(cli(f, t), null, 2)))
+  .action(async (f, t, opts) => {
+    console.log(await cli(f, t, opts))
+  })
 
 program.parse(process.argv)

bin/js2dt.js

@@ -8,6 +8,8 @@ program
   .arguments('<jsonFile> [ramlTypeName]')
   .description('Convert JSON schema to RAML Data Type. ' +
                'Writes to standard output.')
-  .action((f, t) => console.log(cli(f, t)))
+  .action(async (f, t) => {
+    console.log(await cli(f, t))
+  })
 
 program.parse(process.argv)

examples/dt2js_example.js

@@ -1,16 +1,21 @@
 'use strict'
 
-var r2j = require('ramldt2jsonschema')
-var join = require('path').join
-var fs = require('fs')
+const r2j = require('ramldt2jsonschema')
+const join = require('path').join
+const fs = require('fs')
 
-var filePath = join(__dirname, '../test/integration/raml/complex_cat.raml')
-var ramlData = fs.readFileSync(filePath).toString()
+const filePath = join(__dirname, '../test/integration/raml/complex_cat.raml')
+const ramlData = fs.readFileSync(filePath).toString()
 
-r2j.dt2js(ramlData, 'Cat', function (err, schema) {
-  if (err) {
+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()

examples/js2dt_example.js

@@ -1,17 +1,23 @@
 'use strict'
 
-var r2j = require('ramldt2jsonschema')
-var join = require('path').join
-var fs = require('fs')
+const r2j = require('ramldt2jsonschema')
+const join = require('path').join
+const fs = require('fs')
+const yaml = require('js-yaml')
 
-var filePath = join(__dirname, '../test/integration/json/complex_cat.json')
-var jsonData = fs.readFileSync(filePath).toString()
+const filePath = join(__dirname, '../test/integration/json/complex_cat.json')
+const jsonData = fs.readFileSync(filePath).toString()
 
-r2j.js2dt(jsonData, 'Person', function (err, raml) {
-  if (err) {
+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(raml)
-})
+  console.log(yaml.safeDump(raml, { noRefs: true }))
+}
+
+main()