Skip to content

Commit 123e4ba

Browse files
char0nchar0n
committed
docs: add initial documentation
1 parent 916b9e5 commit 123e4ba

File tree

3 files changed

+278
-0
lines changed

3 files changed

+278
-0
lines changed

‎NOTICE‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,10 @@
22
Copyright 2025, Vladimír Gorej
33
@swaggerexpert/json-pointer is licensed under Apache 2.0 license.
44
Copy of the Apache 2.0 license can be found in `LICENSE` file.
5+
6+
JavaScript Object Notation (JSON) Pointer
7+
Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved.
8+
https://datatracker.ietf.org/doc/html/rfc6901
9+
ABNF grammar (grammar.bnf) and certain texts within the README.md file
10+
are licensed under Simplified BSD License - https://spdx.org/licenses/BSD-2-Clause.html.
11+

‎README.md‎

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,273 @@
11
# @swaggerexpert/json-pointer
22

3+
[![npmversion](https://img.shields.io/npm/v/%40swaggerexpert%2Fjson-pointer?style=flat-square&label=npm%20package&color=%234DC81F&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F%40swaggerexpert%2Fjson-pointer)](https://www.npmjs.com/package/@swaggerexpert/json-pointer)
4+
[![npm](https://img.shields.io/npm/dm/@swaggerexpert/json-pointer)](https://www.npmjs.com/package/@swaggerexpert/json-pointer)
5+
[![Test workflow](https://github.com/swaggerexpert/json-pointer/actions/workflows/test.yml/badge.svg)](https://github.com/swaggerexpert/json-pointer/actions)
6+
[![Dependabot enabled](https://img.shields.io/badge/Dependabot-enabled-blue.svg)](https://dependabot.com/)
7+
[![try on RunKit](https://img.shields.io/badge/try%20on-RunKit-brightgreen.svg?style=flat)](https://npm.runkit.com/@swaggerexpert/json-pointer)
8+
[![Tidelift](https://tidelift.com/badges/package/npm/@swaggerexpert%2Fjson-pointer)](https://tidelift.com/subscription/pkg/npm-.swaggerexpert-json-pointer?utm_source=npm-swaggerexpert-json-pointer&utm_medium=referral&utm_campaign=readme)
9+
10+
`@swaggerexpert/json-pointer` is a **parser**, **validator**, **escaper**, **evaluator**, **compiler** and **representer** for [RFC 6901 JavaScript Object Notation (JSON) Pointer](https://datatracker.ietf.org/doc/html/rfc6901).
11+
12+
<table>
13+
<tr>
14+
<td align="right" valign="middle">
15+
<img src="https://cdn2.hubspot.net/hubfs/4008838/website/logos/logos_for_download/Tidelift_primary-shorthand-logo.png" alt="Tidelift" width="60" />
16+
</td>
17+
<td valign="middle">
18+
<a href="https://tidelift.com/subscription/pkg/npm-.swaggerexpert-json-pointer?utm_source=npm-swaggerexpert-json-pointer&utm_medium=referral&utm_campaign=readme">
19+
Get professionally supported @swaggerexpert/json-pointer with Tidelift Subscription.
20+
</a>
21+
</td>
22+
</tr>
23+
</table>
24+
25+
## Table of Contents
26+
27+
- [Getting started](#getting-started)
28+
- [Installation](#installation)
29+
- [Usage](#usage)
30+
- [Parsing](#parsing)
31+
- [Validation](#validation)
32+
- [Escaping](#escaping)
33+
- [Evaluation](#evaluation)
34+
- [Compilation](#compilation)
35+
- [Representation](#representation)
36+
- [Grammar](#grammar)
37+
- [More about JSON Pointer](#more-about-json-pointer)
38+
- [License](#license)
39+
40+
41+
## Getting started
42+
43+
### Installation
44+
45+
You can install `@swaggerexpert/json-pointer` using `npm`:
46+
47+
```sh
48+
$ npm install @swaggerexpert/json-pointer
49+
```
50+
51+
### Usage
52+
53+
`@swaggerexpert/json-pointer` currently supports **parsing**, **validation** ,**evaluation**, **compilation** and **representation**.
54+
Both parser and validator are based on a superset of [ABNF](https://www.rfc-editor.org/rfc/rfc5234) ([SABNF](https://cs.github.com/ldthomas/apg-js2/blob/master/SABNF.md))
55+
and use [apg-lite](https://github.com/ldthomas/apg-lite) parser generator.
56+
57+
#### Parsing
58+
59+
Parsing a JSON Pointer is as simple as importing the **parse** function and calling it.
60+
61+
```js
62+
import { parse } from '@swaggerexpert/json-parse';
63+
64+
const parseResult = parse('/foo/bar');
65+
```
66+
67+
**parseResult** variable has the following shape:
68+
69+
```
70+
{
71+
result: {
72+
success: true,
73+
state: 101,
74+
stateName: 'MATCH',
75+
length: 8,
76+
matched: 8,
77+
maxMatched: 8,
78+
maxTreeDepth: 8,
79+
nodeHits: 49
80+
},
81+
ast: fnast {
82+
callbacks: [
83+
'json-pointer': [Function: jsonPointer],
84+
'reference-token': [Function: referenceToken]
85+
],
86+
init: [Function (anonymous)],
87+
ruleDefined: [Function (anonymous)],
88+
udtDefined: [Function (anonymous)],
89+
down: [Function (anonymous)],
90+
up: [Function (anonymous)],
91+
translate: [Function (anonymous)],
92+
setLength: [Function (anonymous)],
93+
getLength: [Function (anonymous)],
94+
toXml: [Function (anonymous)]
95+
},
96+
computed: [ 'foo', 'bar' ]
97+
}
98+
```
99+
100+
###### Evaluating AST as list of unescaped reference tokens
101+
102+
```js
103+
import { parse } from '@swaggerexpert/json-parse';
104+
105+
const { computed } = parse('/foo/bar'); // computed = ['foo', 'bar']
106+
```
107+
108+
###### Interpreting AST as list of entries
109+
110+
```js
111+
import { parse } from '@swaggerexpert/json-parse';
112+
113+
const parseResult = parse('/foo/bar');
114+
const parts = [];
115+
116+
parseResult.ast.translate(parts);
117+
```
118+
119+
After running the above code, **parts** variable has the following shape:
120+
121+
```js
122+
[
123+
['json-pointer', '/foo/bar'],
124+
['reference-token', 'foo'],
125+
['reference-token', 'bar'],
126+
]
127+
```
128+
129+
###### Interpreting AST as XML
130+
131+
```js
132+
import { parse } from '@swaggerexpert/json-pointer';
133+
134+
const parseResult = parse('/foo/bar');
135+
const xml = parseResult.ast.toXml();
136+
```
137+
138+
After running the above code, **xml** variable has the following content:
139+
140+
```xml
141+
<?xml version="1.0" encoding="utf-8"?>
142+
<root nodes="3" characters="8">
143+
<!-- input string -->
144+
/foo/bar
145+
<node name="json-pointer" index="0" length="8">
146+
/foo/bar
147+
<node name="reference-token" index="1" length="3">
148+
foo
149+
</node><!-- name="reference-token" -->
150+
<node name="reference-token" index="5" length="3">
151+
bar
152+
</node><!-- name="reference-token" -->
153+
</node><!-- name="json-pointer" -->
154+
</root>
155+
```
156+
157+
> NOTE: AST can also be traversed in classical way using [depth first traversal](https://www.tutorialspoint.com/data_structures_algorithms/depth_first_traversal.htm). For more information about this option please refer to [apg-js](https://github.com/ldthomas/apg-js) and [apg-js-examples](https://github.com/ldthomas/apg-js-examples).
158+
159+
#### Validation
160+
161+
Validating a JSON Pointer is as simple as importing one of the validation functions and calling it.
162+
163+
```js
164+
import {
165+
testJSONPointer,
166+
testReferenceToken,
167+
testArrayLocation,
168+
testArrayIndex,
169+
testArrayDash
170+
} from '@swaggerexpert/json-pointer';
171+
172+
testJSONPointer('/foo/bar'); // => true
173+
testReferenceToken('foo'); // => true
174+
testArrayLocation('0'); // => true
175+
testArrayLocation('-'); // => true
176+
testArrayIndex('0'); // => true
177+
testArrayDash('-'); // => true
178+
```
179+
180+
#### Escaping
181+
182+
[comment]: <> (SPDX-FileCopyrightText: Copyright &#40;c&#41; 2013 IETF Trust and the persons identified as the document authors. All rights reserved.)
183+
[comment]: <> (SPDX-License-Identifier: BSD-2-Clause)
184+
185+
Because the characters `'~'` (%x7E) and `'/'` (%x2F) have special
186+
meanings in JSON Pointer, `'~'` needs to be encoded as `'~0'` and `'/'`
187+
needs to be encoded as `'~1'` when these characters appear in a
188+
reference token.
189+
190+
```js
191+
import { escape } from '@swaggerexpert/json-pointer';
192+
193+
escape('~foo'); // => '~0foo'
194+
escape('/foo'); // => '~1foo'
195+
```
196+
197+
[comment]: <> (SPDX-FileCopyrightText: Copyright &#40;c&#41; 2013 IETF Trust and the persons identified as the document authors. All rights reserved.)
198+
[comment]: <> (SPDX-License-Identifier: BSD-2-Clause)
199+
200+
Unescape is performed by first transforming any
201+
occurrence of the sequence `'~1'` to `'/'`, and then transforming any
202+
occurrence of the sequence `'~0'` to `'~'`. By performing the
203+
substitutions in this order, an implementation avoids the error of
204+
turning `'~01'` first into `'~1'` and then into `'/'`, which would be
205+
incorrect (the string '~01' correctly becomes '~1' after transformation).
206+
207+
```js
208+
import { unescape } from '@swaggerexpert/json-pointer';
209+
210+
unescape('~0foo'); // => '~foo'
211+
unescape('~1foo'); // => '/foo'
212+
```
213+
214+
#### Compilation
215+
216+
Compilation is the process of transforming a list of reference tokens into a JSON Pointer.
217+
Reference tokens are escaped before compiled into a JSON Pointer.
218+
219+
```js
220+
import { compile } from '@swaggerexpert/json-pointer';
221+
222+
compile(['~foo', 'bar']); // => '/~0foo/bar'
223+
```
224+
225+
#### Grammar
226+
227+
New grammar instance can be created in following way:
228+
229+
```js
230+
import { Grammar } from '@swaggerexpert/json-pointer';
231+
232+
const grammar = new Grammar();
233+
```
234+
235+
To obtain original ABNF (SABNF) grammar as a string:
236+
237+
```js
238+
import { Grammar } from '@swaggerexpert/json-pointer';
239+
240+
const grammar = new Grammar();
241+
242+
grammar.toString();
243+
// or
244+
String(grammar);
245+
```
246+
247+
## More about JSON Pointer
248+
249+
JSON Pointer is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax
250+
251+
[comment]: <> (SPDX-FileCopyrightText: Copyright &#40;c&#41; 2013 IETF Trust and the persons identified as the document authors. All rights reserved.)
252+
[comment]: <> (SPDX-License-Identifier: BSD-2-Clause)
253+
254+
```abnf
255+
; JavaScript Object Notation (JSON) Pointer ABNF syntax
256+
; https://datatracker.ietf.org/doc/html/rfc6901
257+
json-pointer = *( "/" reference-token )
258+
reference-token = *( unescaped / escaped )
259+
unescaped = %x00-2E / %x30-7D / %x7F-10FFFF
260+
; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
261+
escaped = "~" ( "0" / "1" )
262+
; representing '~' and '/', respectively
263+
264+
; https://datatracker.ietf.org/doc/html/rfc6901#section-4
265+
array-location = array-index / array-dash
266+
array-index = %x30 / ( %x31-39 *(%x30-39) )
267+
; "0", or digits without a leading "0"
268+
array-dash = "-"
269+
```
270+
3271
## License
4272

5273
`@swaggerexpert/json-pointer` is licensed under [Apache 2.0 license](https://github.com/swaggerexpert/json-pointer/blob/main/LICENSE).

‎package.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,10 @@
4242
"pointer",
4343
"parser",
4444
"validator",
45+
"escaper",
4546
"evaluator",
47+
"compile",
48+
"representer",
4649
"rfc6901"
4750
],
4851
"author": "Vladimír Gorej <vladimir.gorej@gmail.com>",

0 commit comments

Comments
 (0)