RAML 1.0 JavaScript Parser

Common errors

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

  cause The package was not installed, or there's a path resolution issue in your environment.
  fix Ensure the package is installed using `npm install raml-1-parser` or `yarn add raml-1-parser`. For new projects, consider installing and using `@raml-org/webapi-parser` instead.

• TypeError: raml.load is not a function

  cause Incorrect import of the `raml` object, or an outdated version of the package where the `load` method might be structured differently.
  fix Verify your import statement: `const raml = require('raml-1-parser');` for CommonJS or `import * as raml from 'raml-1-parser';` for ESM/TypeScript. Ensure you are using a consistent and reasonably recent version (e.g., >=1.1.50 if not migrating).

• Node 4.x or older compatibility errors (e.g., syntax errors with ES6 features)

  cause Using a `raml-1-parser` version that dropped support for Node.js 4.x on an unsupported Node.js runtime.
  fix Upgrade your Node.js runtime to version 6 or higher. `raml-1-parser@1.1.51` and later explicitly require Node.js >=6.

Warnings

• breaking This package is officially deprecated. The RAML organization recommends migrating to `@raml-org/webapi-parser` for all new development and ongoing maintenance. No further feature development or active support is expected for `raml-1-parser`.
  Fix: Migrate your parsing logic to use `@raml-org/webapi-parser`. This will involve significant code changes as the API surface is different.
• breaking Node.js 4 support was dropped with version 1.1.51. Users on older Node.js runtimes will experience errors or require specific older versions of the parser.
  Fix: Upgrade your Node.js runtime to version 6 or higher. The parser officially supports Node.js 6, 8, 11, and later versions since 1.1.51.
• gotcha Versions prior to 1.1.59 had a security vulnerability related to the `serialize-javascript` dependency. While fixed in later `raml-1-parser` versions, older deployments might be at risk.
  Fix: Ensure you are using `raml-1-parser` version 1.1.59 or newer. Alternatively, migrate to the officially supported `@raml-org/webapi-parser`.
• gotcha Version 1.1.54 was a broken npm release and should be avoided. Installing or deploying this specific version will likely lead to operational failures.
  Fix: Do not install or use `raml-1-parser@1.1.54`. Pin your dependency to a working version like 1.1.53 or 1.1.55+.

Install

• npm install fork-raml-1-parser npm
• yarn add fork-raml-1-parser yarn
• pnpm add fork-raml-1-parser pnpm

Imports

• raml
  wrong:

  import raml from 'raml-1-parser';

  correct:

  import * as raml from 'raml-1-parser';

  For TypeScript and modern ESM, use named import for the CommonJS default export. The 'raml' symbol represents the main parser API.
• raml

  const raml = require('raml-1-parser');

  This is the primary and most common import pattern shown in documentation and quickstarts for Node.js CommonJS environments.
• webapi-parser

  import { RamlParser } from '@raml-org/webapi-parser';

  This package is deprecated. For new projects or migration, use `@raml-org/webapi-parser` instead. Import paths and API will differ significantly.

Quickstart

Demonstrates how to synchronously load and parse a local RAML 1.0 file using the `raml-1-parser` library.

const raml = require("raml-1-parser");
const fs = require('fs');
const path = require('path');

// Create a dummy RAML file for the example
const ramlFileName = path.join(__dirname, 'my-api.raml');
const ramlContent = `#%RAML 1.0\ntitle: My Example API\nversion: v1\nbaseUri: https://api.example.com`;
fs.writeFileSync(ramlFileName, ramlContent);

console.log(`Parsing RAML file: ${ramlFileName}`);

try {
  // The 'load' method can often work synchronously for local files.
  const apiJSON = raml.load(ramlFileName);
  console.log("Parsed RAML API JSON:");
  console.log(JSON.stringify(apiJSON, null, 2));
} catch (error) {
  console.error("Error parsing RAML file:", error);
}

// Clean up the dummy file
fs.unlinkSync(ramlFileName);