# @swagger-api/apidom-json-pointer

> Evaluate JSON Pointer expressions against ApiDOM.

Latest version **1.12.1** (published 2026-09-04) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @swagger-api/apidom-json-pointer
pnpm add @swagger-api/apidom-json-pointer
yarn add @swagger-api/apidom-json-pointer
bun add @swagger-api/apidom-json-pointer
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.12.1 |
| Published | 2026-09-04 |
| First published | 2023-02-28 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 371.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 100 |
| Author | Vladimír Gorej |
| Maintainers | swagger-api |

## Links

- npm: https://www.npmjs.com/package/@swagger-api/apidom-json-pointer
- Repository: https://github.com/swagger-api/apidom
- Homepage: https://github.com/swagger-api/apidom#readme
- Issues: https://github.com/swagger-api/apidom/issues
- npm.io page: https://npm.io/package/@swagger-api/apidom-json-pointer

## Dependencies (4)

- [@babel/runtime-corejs3](https://npm.io/package/@babel/runtime-corejs3.md) ^7.26.10
- [@swagger-api/apidom-core](https://npm.io/package/@swagger-api/apidom-core.md) ^1.12.1
- [@swagger-api/apidom-error](https://npm.io/package/@swagger-api/apidom-error.md) ^1.12.1
- [@swaggerexpert/json-pointer](https://npm.io/package/@swaggerexpert/json-pointer.md) ^2.10.1

## Recent versions

- 1.12.1 (latest) — 2026-09-04
- 1.11.5 (v1.11-maintenance) — 2026-09-16
- 1.11.4 — 2026-09-15
- 1.12.0 — 2026-08-03
- 1.11.3 — 2026-06-22
- 1.11.2 — 2026-06-02
- 1.11.1 — 2026-05-12
- 1.11.0 — 2026-04-27
- 1.10.2 — 2026-04-13
- 1.10.1 — 2026-04-07
- 1.10.0 — 2026-04-01
- 1.9.0 — 2026-03-30
- 1.8.0 — 2026-03-20
- 1.7.0 — 2026-03-17
- 1.6.0 — 2026-02-27
- … 119 more at https://npm.io/package/@swagger-api/apidom-json-pointer/versions

## README

# @swagger-api/apidom-json-pointer

`apidom-json-pointer` is a package that evaluates [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) against ApiDOM.

## Installation

You can install this package via [npm CLI](https://docs.npmjs.com/cli) by running the following command:

```sh
 $ 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](https://datatracker.ietf.org/doc/html/rfc6901) and supports all aspects of JSON Pointer.
Uses [@swaggerexpert/json-pointer](https://www.npmjs.com/package/@swaggerexpert/json-pointer) under the hood and fully reflects its API. For additional options and details, refer to the `@swaggerexpert/json-pointer` [documentation](https://www.npmjs.com/package/@swaggerexpert/json-pointer#usage).

Evaluation is contextual to [ApiDOM realm](https://github.com/swaggerexpert/json-pointer?tab=readme-ov-file#apidom-evaluation-realm) - meaning `evaluate` function
expects only ApiDOM as the first argument.

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

### Evaluating

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

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

### Parsing

Parses JSON Pointer into a list of tokens, which can be accessed through the `tree` property of the parse result.

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

const parseResult = parse('/a/b');
// =>
// {
//   result: {
//     success: true,
//     state: 101,
//     stateName: 'MATCH',
//     length: 4,
//     matched: 4,
//     maxMatched: 4,
//     maxTreeDepth: 8,
//     nodeHits: 31
//   },
//   tree: [ 'a', 'b' ],
//   stats: undefined,
//   trace: undefined
// }
```

### Compiling

Compiles a list of tokens into JSON Pointer.

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

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

### Escaping

Escapes/unescapes tokens of JSON Pointer.

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

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

### Transforming URI to JSON Pointer

Handles case of [URI Fragment Identifier Representation](https://datatracker.ietf.org/doc/html/rfc6901#section-6).

```js
import { URIFragmentIdentifier } from '@swagger-api/apidom-json-pointer/modern';

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

### Validating

Validates a JSON Pointer and its tokens.

```js
import {
  testJSONPointer,
  testReferenceToken,
  testArrayLocation,
  testArrayIndex,
  testArrayDash,
} from '@swagger-api/apidom-json-pointer/modern';

testJSONPointer('/a/b'); // => true
testReferenceToken('a'); // => true
testArrayLocation('0'); // => true
testArrayLocation('-'); // => true
testArrayIndex('0'); // => true
testArrayDash('-'); // => true
```

### Invalid JSON Pointers

`JSONPointerError` is the base class for all JSON Pointer errors.

```js
import { JSONPointerError } from '@swagger-api/apidom-json-pointer/modern';
```

If an invalid list of tokens is supplied to `compile` function, `JSONPointerCompileError` is thrown.

```js
import { JSONPointerCompileError } from '@swagger-api/apidom-json-pointer/modern';
```

If an invalid JSON Pointer is supplied to `evaluate` function, `JSONPointerEvaluateError` is thrown.

```js
import { JSONPointerEvaluateError } from '@swagger-api/apidom-json-pointer/modern';
```

If a valid JSON Pointer is supplied to `evaluate` function and the pointer cannot be evaluated against ApiDOM fragment because it is not an object or an array, `JSONPointerTypeError` is thrown.

```js
import { JSONPointerTypeError } from '@swagger-api/apidom-json-pointer/modern';
```

If a valid JSON Pointer is supplied to `evaluate` function and the pointer cannot be evaluated against ApiDOM fragment because the key does not exist in the object, `JSONPointerKeyError` is thrown.

```js
import { JSONPointerKeyError } from '@swagger-api/apidom-json-pointer/modern';
```

If a valid JSON Pointer is supplied to `evaluate` function and the pointer cannot be evaluated against ApiDOM fragment because the index does not exist in the array, `JSONPointerIndexError` is thrown. 

```js
import { JSONPointerIndexError } from '@swagger-api/apidom-json-pointer/modern';
```

If an error occurs in `parse` function, `JSONPointerParseError` is thrown.

```js
import { JSONPointerParseError } 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`.

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

### Evaluating

```js
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 a list of tokens.

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

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

### Compiling

Compiles a list of tokens into JSON Pointer.

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

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

### Escaping

Escapes/unescapes tokens of JSON Pointer.

```js
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](https://datatracker.ietf.org/doc/html/rfc6901#section-6).

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

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

### Invalid JSON Pointers

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

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

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

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

---
_Source: https://npm.io/package/@swagger-api/apidom-json-pointer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._