Registry / serialization / raml-1-parser

raml-1-parser

library1.1.67jsnpmunverified

The `raml-1-parser` is a JavaScript and TypeScript parser library designed for RAML (RESTful API Modeling Language) specifications, offering support for both RAML 0.8 and 1.0 versions. It facilitates the parsing of RAML files from various sources (filesystem paths or URLs) into a structured JSON representation of the API definition, which is useful for API introspection, documentation generation, and tooling development. The current stable version is 1.1.67, with its last significant feature update, including circular reference support, occurring in v1.1.52. This package maintains a slow release cadence, primarily for dependency and security updates. A critical detail for users is that this parser is officially deprecated by the RAML organization. While it once provided comprehensive RAML 1.0 support, its current status means it no longer receives active feature development or consistent security patching. Users are strongly advised to migrate to `@raml-org/webapi-parser` for ongoing maintenance and support.

serialization

npm install raml-1-parser

github ↗package ↗

INSTALL

IMPORT

SIG · RAML-1-PARSER

raml-1-parser

serializationjavascriptv1.1.67

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-1-parser');

✗ import raml from 'raml-1-parser';

This package is primarily a CommonJS module. The main module object is typically imported via `require()`, with functions accessed as properties (e.g., `raml.load`). Direct ES module default imports may not work as expected without `esModuleInterop` enabled in TypeScript or specific Node.js loader configurations.

load

✓ import { load } from 'raml-1-parser';

✗ const load = require('raml-1-parser').load;

While a CommonJS package, its TypeScript declarations indicate `load` is also available as a named export. This allows for direct named imports in TypeScript or destructuring assignments in CommonJS for modern Node.js environments. The function is asynchronous, returning a Promise.

parse

✓ const { parse } = require('raml-1-parser');

✗ import parse from 'raml-1-parser/parse';

Similar to `load`, the `parse` function (which takes raw RAML content as a string) is exposed as a named export, making it accessible via destructuring `require` or named ESM import. It is also an asynchronous function returning a Promise.

Demonstrates how to asynchronously load and parse a RAML 1.0 API definition from a local file, then serialize its parsed JSON representation.

import { load } from 'raml-1-parser'; import * as fs from 'node:fs'; import * as path from 'node:path'; // Create a dummy RAML file for the example const exampleRamlContent = `#%RAML 1.0\n title: My Example API\n version: v1\n baseUri: https://api.example.com/{version}\n /status:\n get:\n description: Check API health\n responses:\n 200:\n body:\n application/json:\n type: object\n properties:\n status: string\n timestamp: datetime\n`; const ramlFileName = path.join(process.cwd(), 'example.raml'); fs.writeFileSync(ramlFileName, exampleRamlContent); async function parseRamlFile() { try { console.log(`Attempting to parse RAML file from: ${ramlFileName}`); // The 'load' function is asynchronous, returning a Promise. // A synchronous version, 'loadRAMLSync', is also available. const apiDefinition = await load(ramlFileName); console.log('Successfully parsed RAML API Definition:'); // The parsed object has a toJSON() method for serializing the model. console.log(JSON.stringify(apiDefinition.toJSON(), null, 2)); } catch (error: any) { console.error('Error parsing RAML file:', error.message || error); if (error.errors) { // Parsers often return detailed error arrays console.error('Validation errors:', JSON.stringify(error.errors, null, 2)); } } finally { // Clean up the dummy file if (fs.existsSync(ramlFileName)) { fs.unlinkSync(ramlFileName); console.log(`Cleaned up temporary file: ${ramlFileName}`); } } } parseRamlFile();

Debug

Known issues

deprecatedThis parser is officially deprecated by the RAML organization. Users are strongly advised to migrate to the actively maintained `@raml-org/webapi-parser` for continued support, new features, and security updates.

fix

Migrate your parsing logic to `@raml-org/webapi-parser`. Consult its documentation for migration guides and API differences.

affects: >=1.1.0

breakingNode.js v4 support was dropped in version 1.1.51. The package now requires a Node.js environment of version 6 or higher to function correctly.

fix

Upgrade your Node.js runtime to version 6 or higher. The package specifies `"node": ">=6"` in its `engines` field.

affects: >=1.1.51

gotchaMultiple past releases (e.g., v1.1.59, v1.1.57, v1.1.56) addressed critical security vulnerabilities in underlying dependencies like `webpack`, `serialize-javascript`, `lodash`, and `z-schema`. Due to the package's deprecated status, future security patches are unlikely. Using older versions may expose applications to known vulnerabilities.

fix

Ensure you are using the latest available version (1.1.67) of `raml-1-parser`. For ongoing security maintenance, migrating to `@raml-org/webapi-parser` is crucial.

affects: <1.1.67

gotchaThe primary `load` and `parse` functions of `raml-1-parser` are asynchronous, returning Promises. The quickstart example in the README might misleadingly show `raml.load(filename)` without `await` or `.then()`, which can lead to uncaught promise rejections or incorrect behavior in modern Node.js environments. Synchronous versions (`loadRAMLSync`, `parseRAMLSync`) are also available but generally less recommended.

fix

Always use `await` with `load` or `parse`, or chain `.then()` and `.catch()` callbacks to handle the Promise. For explicitly synchronous parsing, use `raml.loadRAMLSync(path)` or `raml.parseRAMLSync(content)`.

affects: >=1.1.0

Errors

Common errors & fixes

TypeError: raml_1_parser_1.load is not a function

Attempting to import `load` as a default import or using `require()` destructuring when `esModuleInterop` is not properly configured for a TypeScript project, or in a pure CommonJS file where the specific module export structure isn't handled.

fix

For CommonJS, use `const raml = require('raml-1-parser'); raml.load(...)` or `const { load } = require('raml-1-parser');`. For TypeScript/ESM, ensure `import { load } from 'raml-1-parser';` is used and your `tsconfig.json` includes `"esModuleInterop": true` if importing CommonJS modules with ES module syntax.

Error: Cannot find module 'raml-1-parser'

The package has not been installed or is not resolvable from the current working directory.

fix

Run `npm install raml-1-parser` in your project's root directory.

SyntaxError: Unexpected token 'export' (when using `import` in a CJS file)

Using ES module import syntax (`import { load } from 'raml-1-parser';`) in a JavaScript file that is being interpreted as a CommonJS module by Node.js.

fix

For CommonJS files, use `const { load } = require('raml-1-parser');` or `const raml = require('raml-1-parser'); raml.load(...)`. If you intend to use ES Modules, ensure your `package.json` contains `"type": "module"` or use a `.mjs` file extension and appropriate import paths.

Error parsing RAML file: [multiple validation errors related to types or syntax]

The RAML content being parsed contains syntax errors, invalid data types, or violates the RAML 1.0 specification. This often includes issues like specifying enum values that don't match the declared type, or incorrect formatting for numeric types.

fix

Carefully review your RAML file against the RAML 1.0 specification. Use a RAML-aware editor (like API Workbench, if still supported) for real-time validation. The error message should provide details on the specific validation failures.

Upgrade

Version history

1.1.67latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/raml-org/raml-js-parser-2 ↗

packagehttps://www.npmjs.com/package/raml-1-parser ↗