A complete implementation of JSON Pointer (RFC 6901) for nodejs and modern browsers.
The json-ptr npm package provides utilities for working with JSON Pointers (RFC 6901) and JSON References (RFC 6901). It allows you to create, parse, and resolve JSON Pointers and References, making it easier to navigate and manipulate JSON data structures.
Creating JSON Pointers
This feature allows you to create JSON Pointers from a string path. The example demonstrates creating a JSON Pointer for the path '/foo/bar'.
const ptr = require('json-ptr');
const pointer = ptr.create('/foo/bar');
console.log(pointer.toString()); // '/foo/bar'Resolving JSON Pointers
This feature allows you to resolve a JSON Pointer against a JSON document to retrieve the value at the specified path. The example shows how to get the value 'baz' from the path '/foo/bar' in the given document.
const ptr = require('json-ptr');
const document = { foo: { bar: 'baz' } };
const value = ptr.get(document, '/foo/bar');
console.log(value); // 'baz'Parsing JSON Pointers
This feature allows you to parse a JSON Pointer into its component parts. The example demonstrates parsing the pointer '/foo/bar' into an array of its segments.
const ptr = require('json-ptr');
const parsed = ptr.parse('/foo/bar');
console.log(parsed); // ['foo', 'bar']Handling JSON References
This feature allows you to resolve JSON References within a document. The example shows how to resolve a reference to the path '#/foo/bar' and retrieve the value 'baz'.
const ptr = require('json-ptr');
const document = { foo: { bar: 'baz' }, ref: { '$ref': '#/foo/bar' } };
const value = ptr.resolve(document, document.ref);
console.log(value); // 'baz'The jsonpointer package provides similar functionality for resolving JSON Pointers. It allows you to get and set values in a JSON document using JSON Pointers. Compared to json-ptr, jsonpointer is more focused on basic get and set operations and may not have as extensive support for JSON References.
The json-ref package focuses on resolving JSON References within a document. It provides utilities for dereferencing JSON References and is useful for working with JSON schemas. Compared to json-ptr, json-ref is more specialized in handling JSON References and may not provide as much functionality for working with JSON Pointers.
The jsonpath package provides a way to query JSON documents using JSONPath expressions, which are more powerful and flexible than JSON Pointers. While jsonpath offers more advanced querying capabilities, it is not directly focused on JSON Pointers or References like json-ptr.
A complete implementation of JSON Pointer (RFC 6901) for nodejs and modern browsers.
Supports Relative JSON Pointers. (Example)
I wrote this a few years back when I was unable to find a complete implementation of RFC 6901. It turns out that I now use the hell out of it. I hope you also find it useful.
npm install json-ptr
As of v3.0.0, we provide CJS, ESM, and UMD builds under the dist/ folder when you install the package from NPM, we also have all appropriate references in our package.json file, so your code should just work. If you need a CDN reference for a website or the like, try UNPKG, which picks up our releases automatically.
CDN: https://unpkg.com/browse/json-ptr@3.1.0/dist/json-ptr.min.js.
Both CJS and ESM are supported.
const { JsonPointer } = require('json-ptr');
import { JsonPointer } from 'json-ptr';
The API documentation is generated from code by typedoc and hosted here. Read the docs.
Documentation is always a work in progress, let us know by creating an issue if you need a scenario documented.
There are many uses for JSON Pointers, here's one we encountered when we updated a public API and suddenly had clients sending two different message bodies to our APIs. This example is contrived to illustrate how we supported both new and old incoming messages:
// examples/versions.ts
import { JsonPointer } from 'json-ptr';
export type SupportedVersion = '1.0' | '1.1';
interface PrimaryGuestNamePointers {
name: JsonPointer;
surname: JsonPointer;
honorific: JsonPointer;
}
const versions: Record<SupportedVersion, PrimaryGuestNamePointers> = {
'1.0': {
name: JsonPointer.create('/guests/0/name'),
surname: JsonPointer.create('/guests/0/surname'),
honorific: JsonPointer.create('/guests/0/honorific'),
},
'1.1': {
name: JsonPointer.create('/primary/primaryGuest/name'),
surname: JsonPointer.create('/primary/primaryGuest/surname'),
honorific: JsonPointer.create('/primary/primaryGuest/honorific'),
},
};
interface Reservation extends Record<string, unknown> {
version?: SupportedVersion;
}
/**
* Gets the primary guest's name from the specified reservation.
* @param reservation a reservation, either version 1.0 or bearing a `version`
* property indicating the version.
*/
function primaryGuestName(reservation: Reservation): string {
const pointers = versions[reservation.version || '1.0'];
if (!pointers) {
throw new Error(`Unsupported reservation version: ${reservation.version}`);
}
const name = pointers.name.get(reservation) as string;
const surname = pointers.surname.get(reservation) as string;
const honorific = pointers.honorific.get(reservation) as string;
const names: string[] = [];
if (honorific) names.push(honorific);
if (name) names.push(name);
if (surname) names.push(surname);
return names.join(' ');
}
// The original layout of a reservation (only the parts relevant to our example)
const reservationV1: Reservation = {
guests: [
{
name: 'Wilbur',
surname: 'Finkle',
honorific: 'Mr.',
},
{
name: 'Wanda',
surname: 'Finkle',
honorific: 'Mrs.',
},
{
name: 'Wilma',
surname: 'Finkle',
honorific: 'Miss',
child: true,
age: 12,
},
],
// ...
};
// The new layout of a reservation (only the parts relevant to our example)
const reservationV1_1: Reservation = {
version: '1.1',
primary: {
primaryGuest: {
name: 'Wilbur',
surname: 'Finkle',
honorific: 'Mr.',
},
additionalGuests: [
{
name: 'Wanda',
surname: 'Finkle',
honorific: 'Mrs.',
},
{
name: 'Wilma',
surname: 'Finkle',
honorific: 'Miss',
child: true,
age: 12,
},
],
// ...
},
// ...
};
console.log(primaryGuestName(reservationV1));
console.log(primaryGuestName(reservationV1_1));
prior to v3.0.0 there was a security vulnerability which allowed a developer to perform prototype pollution by sending malformed path segments to json-ptr. If you were one of these developers, you should upgrade to v3.0.0 immediately, and stop using json-ptr to pollute an object's prototype. If you feel you have a legitimate reason to do so, please use another method and leave json-ptr out of it. Such behavior has been disallowed since it can easily be done using plain ol javascript by those determined to violate common best practice.
prior to v2.1.0 there was a security vulnerability which allowed an unscrupulous actor to execute arbitrary code if developers failed to sanitize user input before sending it to json-ptr. If your code does not sanitize user input before sending it to json-ptr, your project is vulnerable and you should upgrade to v3.0.0 immediately. And while your at it, start sanitized user input before sending it to any library!
As was rightly pointed out in this issue, I should have rolled the major version at v1.3.0 instead of the minor version due to breaking changes to the API. Not the worst blunder I've made, but my apologies all the same. Since the ship has sailed, I'm boosting the visibility of these breaking changes.
In version v1.3.0 of the library, global functions were moved to static functions of the JsonPointer class. There should be no difference in arguments or behavior. If you were previously importing the global functions it is a small change to destructure them and have compatible code.
We're maintaining near 100% test coverage. Visit our circleci build page and drill down on a recent build's build and test step to see where we're at. It should look something like:
=============================== Coverage summary ===============================
Statements : 100% ( 270/270 )
Branches : 100% ( 172/172 )
Functions : 100% ( 49/49 )
Lines : 100% ( 265/265 )
================================================================================
We use mocha so you can also clone the code and:
$ npm install
$ npm test
Once you've run the tests on the command line you can open up ./tests.html in the browser of your choice.
WARNING! These performance metrics are quite outdated. We'll be updating as soon as we have time.
This repository has a companion repository that makes some performance comparisons between json-ptr, jsonpointer and json-pointer.
All timings are expressed as nanoseconds:
.flatten(obj)
...
MODULE | METHOD | COMPILED | SAMPLES | AVG | SLOWER
json-pointer | dict | | 10 | 464455181 |
json-ptr | flatten | | 10 | 770424039 | 65.88%
jsonpointer | n/a | | - | - |
.has(obj, pointer)
...
MODULE | METHOD | COMPILED | SAMPLES | AVG | SLOWER
json-ptr | has | compiled | 1000000 | 822 |
json-ptr | has | | 1000000 | 1747 | 112.53%
json-pointer | has | | 1000000 | 2683 | 226.4%
jsonpointer | n/a | | - | - |
.has(obj, fragmentId)
...
MODULE | METHOD | COMPILED | SAMPLES | AVG | SLOWER
json-ptr | has | compiled | 1000000 | 602 |
json-ptr | has | | 1000000 | 1664 | 176.41%
json-pointer | has | | 1000000 | 2569 | 326.74%
jsonpointer | n/a | | - | - |
.get(obj, pointer)
...
MODULE | METHOD | COMPILED | SAMPLES | AVG | SLOWER
json-ptr | get | compiled | 1000000 | 590 |
json-ptr | get | | 1000000 | 1676 | 184.07%
jsonpointer | get | compiled | 1000000 | 2102 | 256.27%
jsonpointer | get | | 1000000 | 2377 | 302.88%
json-pointer | get | | 1000000 | 2585 | 338.14%
.get(obj, fragmentId)
...
MODULE | METHOD | COMPILED | SAMPLES | AVG | SLOWER
json-ptr | get | compiled | 1000000 | 587 |
json-ptr | get | | 1000000 | 1673 | 185.01%
jsonpointer | get | compiled | 1000000 | 2105 | 258.6%
jsonpointer | get | | 1000000 | 2451 | 317.55%
json-pointer | get | | 1000000 | 2619 | 346.17%
These results have been elided because there is too much detail in the actual. Your results will vary slightly depending on the resources available where you run it.
It is important to recognize in the performance results that compiled options are faster. As a general rule, you should compile any pointers you'll be using repeatedly.
2022-02-02 — 3.1.0
.set() methods, which in turn rely on setValueAtPath(), and using the force argument to enable creating an object graph, one character path segments were interpreted as numbers, which resulted in unintended object graphs being created when the character was not an integer.2021-10-26 — 3.0.0 Potential Security Vulnerability Patched
json-ptr to pollute an object's prototype by passing invalid path segments to the set/unset operations. This behavior has been disallowed.2021-05-14 — 2.2.0 Added Handling for Relative JSON Pointers
2021-05-12 — 2.1.1 Bug fix for #36
undefined as intended. The original behavior has been restored.2021-05-12 — 2.1.0 Bug fixes for #28 and #30; Security Vulnerability Patched
When compiling the accessors for quickly accessing points in an object graph, the .get() method was not properly delimiting single quotes. This error caused the get operation to throw an exception in during normal usage. Worse, in cases where malicious user input was sent directly to json-ptr, the failure to delimit single quotes allowed the execution of arbitrary code (an injection attack). The first of these issues was reported in #28 by @mprast, the second (vulnerability) by @zpbrent. Thanks also to @elimumford for the actual code used for the fix.
If your code sent un-sanitized user input to the .get() method of json-ptr, your project was susceptible to this security vulnerability!
2020-10-21 — 2.0.0 Breaking Change
json-ptr to support pointers across the prototype, I'm rolling the major version number because you're now broken.BEWARE of Breaking Changes at v1.3.0!
2020-07-20 — 1.3.2
tslib dependency.2020-07-10 — 1.3.0 BREAKING CHANGES
JsonPointer type. See Where did the Global Functions Go?.unset() function contributed by @chrishalbert, updated dependencies.2019-09-14 — 1.2.0
.concat function contributed by @vuwuv, updated dependencies.2019-03-10 — 1.1.2
2016-07-26 — 1.0.1
2016-01-12 — 1.0.0
.list(obj, fragmentId).2016-01-02 — 0.3.0
.list function.map function2014-10-21 — 0.2.0 Added #list function to enumerate all properties in a graph, producing fragmentId/value pairs.
FAQs
A complete implementation of JSON Pointer (RFC 6901) for nodejs and modern browsers.
The npm package json-ptr receives a total of 241,569 weekly downloads. As such, json-ptr popularity was classified as popular.
We found that json-ptr demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.
Security News
Research
The Socket Research Team uncovered a malicious Python package typosquatting the popular 'fabric' SSH library, silently exfiltrating AWS credentials from unsuspecting developers.