@swagger-api/apidom-parser-adapter-json

What is @swagger-api/apidom-parser-adapter-json?

@swagger-api/apidom-parser-adapter-json is a parser adapter for the ApiDOM library that allows you to parse and manipulate JSON documents. It is particularly useful for working with API specifications and other structured data formats.

What are @swagger-api/apidom-parser-adapter-json's main functionalities?

Parsing JSON

This feature allows you to parse a JSON string into an ApiDOM structure. The code sample demonstrates how to use the `parse` function to convert a JSON string into a parsed object.

const { parse } = require('@swagger-api/apidom-parser-adapter-json');

const jsonString = '{"key": "value"}';
const parsed = parse(jsonString);
console.log(parsed);

Serializing JSON

This feature allows you to serialize an ApiDOM structure back into a JSON string. The code sample demonstrates how to use the `serialize` function to convert an ApiDOM object into a JSON string.

const { serialize } = require('@swagger-api/apidom-parser-adapter-json');

const apiDomObject = { key: 'value' };
const jsonString = serialize(apiDomObject);
console.log(jsonString);

Other packages similar to @swagger-api/apidom-parser-adapter-json

json5

The `json5` package provides a JSON parser and serializer that is more lenient than the standard JSON. It allows for comments, trailing commas, and other features not supported by standard JSON. Compared to @swagger-api/apidom-parser-adapter-json, `json5` focuses on providing a more flexible JSON format rather than integrating with ApiDOM.

fast-json-stringify

The `fast-json-stringify` package is a fast and efficient JSON stringifier that uses JSON schema to optimize the serialization process. It is designed for performance and can be significantly faster than the standard `JSON.stringify` method. Unlike @swagger-api/apidom-parser-adapter-json, it does not provide parsing capabilities and is focused solely on serialization.

ajv

The `ajv` package is a JSON schema validator that can be used to validate JSON data against a schema. It is highly performant and supports a wide range of JSON schema features. While it does not provide parsing or serialization capabilities like @swagger-api/apidom-parser-adapter-json, it is useful for ensuring that JSON data conforms to a specified schema.

README

@swagger-api/apidom-parser-adapter-json

@swagger-api/apidom-parser-adapter-json is a parser adapter for the JSON format.

CST produced by lexical analysis is syntactically analyzed and ApiDOM structure using base ApiDOM namespace is produced.

Installation

After prerequisites for installing this package are satisfied, you can install it via npm CLI by running the following command:

 $ npm install @swagger-api/apidom-parser-adapter-json

Parse phases

The parse stage takes JSON string and produces ApiDOM structure using base ApiDOM namespace. There are two phases of parsing: Lexical Analysis and Syntactic Analysis.

Lexical Analysis

Lexical Analysis will take a JSON string and turn it into a stream of tokens. tree-sitter / web-tree-sitter is used as an underlying lexical analyzer.

Syntactic Analysis

Syntactic Analysis will take a stream of tokens and turn it into an ApiDOM representation. CST produced by lexical analysis is syntactically analyzed and ApiDOM structure using base ApiDOM namespace is produced.

Direct Syntactical analysis

This analysis directly turns tree-sitter CST into ApiDOM. Single traversal is required which makes it super performant, and it's the default analysis used.

import { parse } from '@swagger-api/apidom-parser-adapter-json';

const parseResult = await parse('{"prop": "value"}', {
  syntacticAnalysis: 'direct',
});

Indirect Syntactic analysis

This analysis turns trees-sitter CST into JSON AST representation. Then JSON AST is turned into ApiDOM. Two traversals are required, which makes indirect analysis less performant than direct one. Thought less performant, having JSON AST representation allows us to do further complex analysis.

import { parse } from '@swagger-api/apidom-parser-adapter-json';

const parseResult = await parse('{"prop": "value"}', {
  syntacticAnalysis: 'indirect',
});

Parser adapter API

This parser adapter is fully compatible with parser adapter interface required by @swagger-api/apidom-parser and implements all required properties.

mediaTypes

Defines list of media types that this parser adapter recognizes.

['application/json']

detect

Detection is based on using JSON.parse to indicate whether the provided source string is or isn't JSON string.

namespace

This adapter exposes an instance of base ApiDOM namespace.

parse

parse function consumes various options as a second argument. Here is a list of these options:

Option	Type	Default	Description
sourceMap	Boolean	false	Indicate whether to generate source maps.
syntacticAnalysis	String	direct	Indicate type of syntactic analysis

All unrecognized arbitrary options will be ignored.

Usage

This parser adapter can be used directly or indirectly via @swagger-api/apidom-parser.

Direct usage

During direct usage you don't need to provide mediaType as the parse function is already pre-bound with supported media types.

import { parse, detect } from '@swagger-api/apidom-parser-adapter-json';

// detecting
await detect('{"prop": "value"}'); // => true
await detect('test'); // => false

// parsing
const parseResult = await parse('{"prop": "value"}', { sourceMap: true });

Indirect usage

You can omit the mediaType option here, but please read Word on detect vs mediaTypes before you do so.

import ApiDOMParser from '@swagger-api/apidom-parser';
import * as jsonParserAdapter from '@swagger-api/apidom-parser-adapter-json';

const parser = new ApiDOMParser();

parser.use(jsonParserAdapter);

const parseResult = await parser.parse('{"prop", "value"}', { mediaType: jsonParserAdapter.mediaTypes.latest('json') });

Changelog

1.0.0-beta.6 (2024-12-30)

Features

• ls: add support for OpenAPI 3.0.4 (#4628) (d973f6d), closes #4612
• ns-openapi-3-0: add support for OpenAPI 3.0.4 (#4613) (e1c2eb7), closes #4612
• parser-adapter-openapi-json-3-0: add support for OpenAPI 3.0.4 (#4616) (174ca57), closes #4612
• parser-adapter-openapi-yaml-3-0: add support for OpenAPI 3.0.4 (#4617) (db2140e), closes #4612
• reference: add support for OpenAPI 3.0.4 (#4624) (0dcb105), closes #4612