- The resolved JSON dataExample:
`javascript import { parse } from 'jsonref';const schema = { "definitions": { "user": { "type": "object", "properties": { "id": { "type": "string" } } } }, "properties": { "currentUser": { "$ref": "#/definitions/user" } } };
const resolved = await parse(schema);
`
$3 Navigate or modify JSON data using JSON Pointer syntax.
Parameters: -
data (object): The object to traverse - path (string | string[]): JSON Pointer path (e.g., "/users/0/name" or ["users", "0", "name"]) - value (any, optional): Value to set at the specified pathReturns: The value at the path, or the modified object if setting a value
Examples:
`javascript import { pointer } from 'jsonref';const data = { users: [ { name: "Alice", age: 30 }, { name: "Bob", age: 25 } ] };
// Get a value const name = pointer(data, "/users/0/name"); // "Alice"
// Set a value pointer(data, "/users/0/age", 31); console.log(data.users[0].age); // 31
// Create nested paths pointer(data, "/users/0/address/city", "New York");
`
$3 The library also exports several utility functions for advanced use cases:
-
isRef(obj) - Check if an object is a JSON Reference - isAnnotated(obj) - Check if an object has been processed by jsonref - getMeta(obj) - Get metadata from a processed object - normalize(obj) - Normalize $id and $ref values in an object - scope(obj) - Get the resolution scope of an object
Usage Examples
$3
`javascript import { parse } from 'jsonref';const schema = { "$id": "https://example.com/person.schema.json", "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "age": { "$ref": "#/definitions/positiveInteger" } }, "definitions": { "positiveInteger": { "type": "integer", "minimum": 0 } } };
const resolved = await parse(schema); console.log(resolved.properties.age); // { type: "integer", minimum: 0 }
`
$3
`javascript import { parse } from 'jsonref';const store = {}; // Reuse this store across multiple parse operations
const schema1 = { "allOf": [{ "$ref": "https://json-schema.org/draft-07/schema" }] };
const schema2 = { "allOf": [{ "$ref": "https://json-schema.org/draft-07/schema" }] };
// First parse will fetch the external reference const resolved1 = await parse(schema1, { store, retriever });
// Second parse will use cached reference (faster) const resolved2 = await parse(schema2, { store, retriever });
`
$3
`javascript import { pointer } from 'jsonref';const config = { database: { host: "localhost", port: 5432, credentials: { username: "admin", password: "secret" } }, features: ["auth", "logging"] };
// Navigate nested objects const host = pointer(config, "/database/host"); // "localhost"
// Work with arrays const firstFeature = pointer(config, "/features/0"); // "auth"
// Modify existing values pointer(config, "/database/port", 3306);
// Create new nested structures pointer(config, "/cache/redis/host", "redis.example.com"); console.log(config.cache); // { redis: { host: "redis.example.com" } }
`
$3 #### Browser with fetch
`javascript function retriever(url) { return fetch(url, { method: 'GET', headers: { 'Accept': 'application/json' } }).then(response => { if (!response.ok) { throw new Error(HTTP ${response.status}: ${response.statusText}); } return response.json(); }); }`#### Node.js with built-in fetch (Node 18+)
`javascript import { fetch } from 'undici'; // or use built-in fetch in Node 18+function retriever(url) { return fetch(url).then(response => response.json()); }
`#### Node.js with file system support
`javascript import fs from 'fs/promises'; import path from 'path';function retriever(url) { if (url.startsWith('file://')) { const filePath = url.replace('file://', ''); return fs.readFile(filePath, 'utf8').then(JSON.parse); } // Handle HTTP URLs return fetch(url).then(response => response.json()); }
`
Error Handling The library provides comprehensive error handling for various scenarios:
`javascript import { parse } from 'jsonref';try { // This will throw an error because no retriever is provided for external reference const schema = { "$ref": "https://example.com/schema.json" }; await parse(schema); // Throws: no_retriever } catch (error) { console.error('Error:', error.message); }
// Proper error handling with retriever async function safeRetriever(url) { try { const response = await fetch(url); if (!response.ok) { throw new Error(
Failed to fetch ${url}: ${response.status}); } return await response.json(); } catch (error) { throw new Error(Network error: ${error.message}); } }`
TypeScript Support Full TypeScript definitions are included:
`typescript import { parse, pointer, isRef, ParseOptions } from 'jsonref';interface Schema { type: string; properties?: Record; }
const options: ParseOptions = { retriever: async (url: string) => { const response = await fetch(url); return response.json(); } };
const schema: Schema = { type: "object", properties: { user: { "$ref": "#/definitions/user" } } };
const resolved = await parse(schema, options);
`
Performance Tips 1. Reuse stores for better performance when parsing multiple documents with shared references 2. Cache external references by implementing a smart retriever function 3. Use scopes when working with relative references to avoid unnecessary network requests
`javascript // Efficient caching retriever const cache = new Map();function cachingRetriever(url) { if (cache.has(url)) { return Promise.resolve(cache.get(url)); } return fetch(url) .then(response => response.json()) .then(data => { cache.set(url, data); return data; }); }
`
Browser Support jsonref works in all modern browsers that support: - Promises (or use a polyfill) - Object.keys, Object.defineProperty - JSON.parse/JSON.stringify
For older browsers, consider using polyfills for missing features.
License MIT License - see the LICENSE file for details.
Contributing Contributions are welcome! Please read our contributing guidelines and ensure all tests pass:
`bash pnpm install pnpm test pnpm run coverage``