@swagger-api/apidom-json-pointer

What is @swagger-api/apidom-json-pointer?

@swagger-api/apidom-json-pointer is an npm package that provides utilities for working with JSON Pointers, which are a way to reference specific parts of a JSON document. This package is particularly useful for navigating and manipulating JSON data structures in a standardized way.

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

Creating JSON Pointers

This feature allows you to create a JSON Pointer instance from a string. The created pointer can then be used to reference specific parts of a JSON document.

const { JsonPointer } = require('@swagger-api/apidom-json-pointer');
const pointer = JsonPointer.create('/path/to/element');
console.log(pointer.toString()); // Outputs: /path/to/element

Resolving JSON Pointers

This feature allows you to resolve a JSON Pointer against a JSON document to retrieve the value at the specified location.

const { JsonPointer } = require('@swagger-api/apidom-json-pointer');
const document = { path: { to: { element: 'value' } } };
const pointer = JsonPointer.create('/path/to/element');
const value = pointer.resolve(document);
console.log(value); // Outputs: 'value'

Setting Values with JSON Pointers

This feature allows you to set a value at a specific location in a JSON document using a JSON Pointer.

const { JsonPointer } = require('@swagger-api/apidom-json-pointer');
const document = { path: { to: { element: 'value' } } };
const pointer = JsonPointer.create('/path/to/element');
pointer.set(document, 'newValue');
console.log(document.path.to.element); // Outputs: 'newValue'

Other packages similar to @swagger-api/apidom-json-pointer

jsonpointer

The 'jsonpointer' package provides similar functionality for working with JSON Pointers. It allows you to get and set values in JSON documents using JSON Pointers. Compared to @swagger-api/apidom-json-pointer, 'jsonpointer' is more widely used and has a simpler API.

json-ptr

The 'json-ptr' package is another alternative for working with JSON Pointers. It offers a comprehensive set of features for creating, resolving, and manipulating JSON Pointers. It also includes additional utilities for working with JSON References. 'json-ptr' is more feature-rich compared to @swagger-api/apidom-json-pointer.

README

@swagger-api/apidom-json-pointer

apidom-json-pointer is a package that evaluates JSON Pointer against ApiDOM.

Installation

You can install this package via npm CLI by running the following command:

 $ npm install @swagger-api/apidom-json-pointer

Modern API

This is the recommended API for use in new projects. It is fully compliant with RFC 6901 and supports all aspects of JSON Pointer. Uses @swaggerexpert/json-pointer under the hood and fully reflects its API.

Evaluation is contextual to ApiDOM realm - meaning evaluate function expects only ApiDOM as the first argument.

import { evaluate } from '@swagger-api/apidom-json-pointer/modern';

Legacy API

This is a legacy API not recommended for use in new projects. It is provided for backward compatibility only. The legacy API implementation is not RFC 6901 compliant, nor does it support all features of JSON Pointer.

Importing legacy API from @swagger-api/apidom-json-pointer is equivalent to importing from @swagger-api/apidom-json-pointer/legacy.

import { evaluate } from '@swagger-api/apidom-json-pointer';

or

import { evaluate } from '@swagger-api/apidom-json-pointer/legacy';

Evaluating

import { ObjectElement } from '@swagger-api/apidom-core';
import { evaluate } from '@swagger-api/apidom-json-pointer';

const apidom = new ObjectElement({ a: { b: 'c' } });
const result =  evaluate('/a/b', apidom);
// => StringElement('c')

Parsing

Parses JSON Pointer into list of tokens.

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

const tokens = parse('/a/b'); // => ['a', 'b']

Compiling

Compiles list of tokens into JSON Pointer.

import { compile } from '@swagger-api/apidom-json-pointer';

const jsonPointer = compile(['a', 'b']); // => '/a/b'

Escaping

Escapes/unescapes tokens of JSON Pointer.

import { escape, unescape } from '@swagger-api/apidom-json-pointer';

escape('~a/'); // => '~0a~1'
unescape('~0a~1'); // => '~a/'

Transforming URI to JSON Pointer

Handles case of URI Fragment Identifier Representation.

import { uriToPointer } from '@swagger-api/apidom-json-pointer';

uriToPointer('https://example.com/path/#/a/b'); // => '/a/b'

Invalid JSON Pointers

If invalid JSON Pointer is supplied to parse or evaluate functions, InvalidJsonPointerError is thrown.

import { InvalidJsonPointerError } from '@swagger-api/apidom-json-pointer';

If valid JSON Pointer is supplied to evaluate function and the pointer cannot be evaluated against ApiDOM fragment, EvaluationJsonPointerError is thrown.

import { EvaluationJsonPointerError } from '@swagger-api/apidom-json-pointer';

Changelog

1.0.0-beta.43 (2025-06-13)

Features

• ls: add OpenAPI 3.x validation for Paramter.style fixed field (#4955) (0fa98c8), closes #2355