ApiDOM parses API specifications into a semantic data model. It has two parsing modes — strict and non-strict.

Parse a file or URL

The most common starting point. Pass a file path or URL to the @speclynx/apidom-reference package and ApiDOM autodetects the specification type and version.

import { parse } from '@speclynx/apidom-reference';

const fileResult = await parse('/path/to/openapi.json');
const urlResult = await parse('https://example.com/openapi.json');

To explicitly force a specific data model instead of autodetection, use the mediaType option:

import { parse } from '@speclynx/apidom-reference';

const result = await parse('/path/to/openapi.json', {
  parse: { mediaType: 'application/openapi+json;version=3.1.2' }
});

Parse a string

When you already have the specification content in memory, pass it directly to a parser adapter. Unlike the reference package, parser adapters use non-strict mode by default.

import { parse } from '@speclynx/apidom-parser-adapter-openapi-json-3-1';

const result = await parse('{"openapi":"3.1.2","info":{"title":"My API"}}');

If you need to handle multiple formats, use ApiDOMParser to mount several adapters and let it autodetect the right one:

import ApiDOMParser from '@speclynx/apidom-parser';
import * as openApiJsonAdapter from '@speclynx/apidom-parser-adapter-openapi-json-3-1';
import * as openApiYamlAdapter from '@speclynx/apidom-parser-adapter-openapi-yaml-3-1';

const parser = new ApiDOMParser();
parser.use(openApiJsonAdapter);
parser.use(openApiYamlAdapter);

const result = await parser.parse('{"openapi":"3.1.2","info":{"title":"My API"}}');

Switch to non-strict mode

The reference package uses strict mode by default. Need error recovery on malformed input? Switch to non-strict mode. Non-strict mode also unlocks source maps and style preservation.

import { parse } from '@speclynx/apidom-reference';

const result = await parse('/path/to/openapi.json', {
  parse: { parserOpts: { strict: false, sourceMap: true, style: true } }
});

When using a parser adapter directly, options are passed at the top level:

import { parse } from '@speclynx/apidom-parser-adapter-openapi-json-3-1';

const result = await parse(source, { sourceMap: true, style: true });

Source maps

Source maps track the exact position of every element in the original document. Positions use UTF-16 code units, making them directly compatible with the Language Server Protocol, VSCode, and Monaco Editor.

import { parse } from '@speclynx/apidom-parser-adapter-openapi-json-3-1';

const result = await parse(source, { sourceMap: true });

Each element in the data model carries six position properties, all zero-based:

element.startLine;       // line where element begins
element.startCharacter;  // column where element begins
element.startOffset;     // character offset from document start
element.endLine;         // line where element ends
element.endCharacter;    // column where element ends
element.endOffset;       // character offset where element ends

Style preservation

Style preservation captures format-specific details like indentation, key ordering, and raw number representation. This is what makes lossless round-trips possible — parse a document and serialize it back without losing formatting.

import { parse } from '@speclynx/apidom-parser-adapter-openapi-json-3-1';

const result = await parse(source, { style: true });