Registry / serialization / raml-parser

raml-parser

JSON →
library0.8.18jsnpmunverified

The `raml-parser` package provides a JavaScript implementation for parsing RAML (RESTful API Modeling Language) version 0.8 specifications. It is built using CoffeeScript and is designed for use in both Node.js environments via CommonJS `require` and directly in web browsers by including a script tag. The current stable version is 0.8.18. This parser specifically targets the RAML 0.8 specification, which is an older standard. For projects requiring support for RAML 1.0, a separate, newer parser (`raml-js-parser-2`) is available and recommended. Release cadence for `raml-parser` is infrequent, focusing primarily on bug fixes and maintenance for the 0.8 specification, such as recent patches addressing circular references in JSON schemas and `$ref`erenced schema support. Its primary differentiator is its strict adherence to the deprecated RAML 0.8 standard, making it suitable mainly for maintaining legacy systems built on that specific version.

serializationhttp-networking
npm install raml-parser
github ↗package ↗
INSTALL
IMPORT
SIG · RAML-PARSER
R
raml-parser
serializationjavascriptv0.8.18
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

raml
✓ const raml = require('raml-parser');
✗ import raml from 'raml-parser';
This package is a CommonJS module, primarily designed for Node.js environments using `require()`. Attempting to use ES module `import` syntax will result in errors.
RAML.Parser
✓ RAML.Parser.loadFile('myAPI.raml')
✗ const raml = require('raml-parser'); raml.loadFile('myAPI.raml')
For in-browser usage, the parser registers a global `RAML.Parser` object. The Node.js `require('raml-parser')` pattern is not applicable in the browser environment.
loadFile
✓ raml.loadFile('path/to/myAPI.raml').then(...);
✗ raml.parseFile('path/to/myAPI.raml').then(...);
The primary method for loading RAML from a file is `loadFile`, returning a Promise. `load` is used for string-based definitions, and `composeFile`/`compose` for abstract syntax tree (AST) generation.

This quickstart demonstrates how to parse a RAML 0.8 file and a RAML 0.8 string into an object model, and also how to generate an Abstract Syntax Tree (AST) from a RAML string, using both `loadFile`/`load` and `compose` methods.

const raml = require('raml-parser'); const fs = require('fs'); // Create a dummy RAML file for demonstration const dummyRamlContent = [ '#%RAML 0.8', '---', 'title: My Example API', 'baseUri: http://api.example.com/{version}', 'version: v1', '/users:', ' get:', ' description: Retrieve a list of users', ' responses:', ' 200:', ' body:', ' application/json:', ' schema: |', ' { "$schema": "http://json-schema.org/draft-04/schema#", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }', ' type: array', ' items: userDef', ' post:', ' description: Create a new user', ' body:', ' application/json:', ' schema: userDef', 'resourceTypes:', ' - userDef: { type: object, properties: { id: { type: integer }, name: { type: string } } }' ].join('\n'); fs.writeFileSync('myAPI.raml', dummyRamlContent); // 1. Load from a RAML file raml.loadFile('myAPI.raml').then( function(data) { console.log('--- Parsed API from file (Object Model) ---'); console.log(JSON.stringify(data, null, 2)); }, function(error) { console.error('Error parsing file: ' + error); }); // 2. Load from a string definition const definitionString = [ '#%RAML 0.8', '---', 'title: My String API', 'baseUri: http://string-api.example.com', '/products:', ' get:', ' description: Get all products', ' responses: { 200: { body: { "application/json": { example: "[{ \"id\": 1, \"name\": \"Product A\" }]" } } } }' ].join('\n'); raml.load(definitionString).then( function(data) { console.log('\n--- Parsed API from string (Object Model) ---'); console.log(JSON.stringify(data, null, 2)); }, function(error) { console.error('Error parsing string: ' + error); }); // 3. Compose an AST from a RAML string raml.compose(definitionString).then(function(rootNode) { console.log('\n--- Composed AST from string ---'); console.log('Root Node Type:', rootNode.kind); console.log('Root Node Value:', rootNode.value); }, function(error) { console.error('Error composing AST from string: ' + error); }); // Clean up the dummy file process.on('exit', () => { if (fs.existsSync('myAPI.raml')) { fs.unlinkSync('myAPI.raml'); } });
raml-parser --version
Debug
Known issues
gotchaThis parser exclusively supports RAML 0.8. It will not correctly parse or validate RAML 1.0 specifications, which include significant syntax and feature changes.
fix
For RAML 1.0 support, use the `raml-js-parser-2` package instead, which is specifically designed for the newer specification.
affects: <=0.8.18
deprecatedThe RAML 0.8 specification is considered deprecated. Most new API development and tooling has transitioned to RAML 1.0. This package is primarily for maintenance of legacy RAML 0.8 projects.
fix
Consider migrating your API definitions to RAML 1.0 and utilizing `raml-js-parser-2` for future development to leverage updated features and tooling support.
affects: >=0.0.1
breakingAsynchronous HTTP requests became the default behavior for parsing remote RAML definitions in version 0.8.11. This change might affect applications that relied on synchronous behavior.
fix
Ensure your code correctly handles Promises returned by `loadFile` and other methods that might involve fetching remote resources. No direct fix is available to revert to synchronous behavior.
affects: >=0.8.11
gotchaSupport for `$ref`erenced JSON schemas, inclusion, and validation was introduced in v0.8.17. Prior versions will fail to correctly process RAML files utilizing these features within their JSON schema definitions.
fix
Upgrade to `raml-parser` version 0.8.17 or higher to ensure proper handling of `$ref`erenced JSON schemas.
affects: <0.8.17
gotchaAn issue with circular references in recursive JSON schema referencing was fixed in v0.8.18. Older versions may encounter infinite loops or incorrect parsing results when dealing with such schemas.
fix
Update to `raml-parser` version 0.8.18 to correctly handle JSON schemas with circular references.
affects: <0.8.18
gotchaThe `applySchemas` feature flag, controlling schema transformations, was added in v0.8.15. Without explicit control of this flag, behavior might vary across versions or depend on default settings.
fix
Review the documentation for `applySchemas` in v0.8.15+ and update your parsing logic if specific schema transformation control is required.
affects: <0.8.15
Errors
Common errors & fixes
TypeError: raml.loadFile is not a function
Attempting to use Node.js `require()` syntax (`raml.loadFile`) in a browser environment without the global `RAML.Parser` object being loaded.
fix
In the browser, ensure `raml-parser.min.js` is included via a `<script>` tag and use `RAML.Parser.loadFile()` or `RAML.Parser.load()`.
Error parsing: YAML parsing error: [details]
The input RAML definition (file or string) contains syntax errors, making it invalid YAML or RAML 0.8.
fix
Carefully review your RAML file or string for correct YAML and RAML 0.8 syntax. Use a linter or validator for RAML 0.8 if available.
Error parsing: ENOENT: no such file or directory, open 'myAPI.raml'
`raml.loadFile()` was called with a path to a RAML file that does not exist or is inaccessible at the specified location.
fix
Verify the file path provided to `raml.loadFile()` is correct and that the Node.js process has read permissions for the file.
TypeError: Cannot read properties of undefined (reading 'then')
The `loadFile` or `load` method did not return a Promise, possibly due to an invalid input or an unhandled synchronous error before the promise could be created.
fix
Ensure the input to `loadFile` or `load` is valid (e.g., a string for `load`, a valid path for `loadFile`) and that the parser is correctly initialized. This can also happen if the `raml` object itself is undefined or incorrectly imported.
Upgrade
Version history
0.8.18latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
9 hits · last 30 days
node
8
Resources
githubhttps://github.com/raml-org/raml-js-parser ↗
packagehttps://www.npmjs.com/package/raml-parser ↗
raml-parser — npm install raml-parser · libregistry