Registry /
http-networking / openapi-path-templating
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse
✓ import { parse } from 'openapi-path-templating';
✗ const parse = require('openapi-path-templating').parse;
The library primarily uses named exports. Ensure you destructure named exports when using CommonJS, or use ESM import syntax.
validate
✓ import { validate } from 'openapi-path-templating';
✗ import validate from 'openapi-path-templating';
Individual functions are named exports, not default exports. This applies to all utility functions like `validate`, `resolve`, `match`, `normalize`, and `isIdentical`.
match
✓ import { match } from 'openapi-path-templating';
✗ const { match } = require('openapi-path-templating');
For TypeScript projects, the library ships with type definitions, making ESM imports the recommended approach for optimal type inference and modern module bundling.
normalize
✓ import { normalize } from 'openapi-path-templating';
The `normalize` function was added in v2.2.0 for standard path normalization.
isIdentical
✓ import { isIdentical } from 'openapi-path-templating';
The `isIdentical` predicate was introduced in v2.1.0 to compare two path templates for equivalence in structure and parameter names.
Demonstrates parsing, validating, resolving, matching, normalizing, and identity checking OpenAPI path templates against concrete URLs and parameter objects.
import { parse, validate, resolve, match, normalize, isIdentical } from 'openapi-path-templating';
const openApiPath = '/users/{userId}/posts/{postId}';
const concretePath = '/users/123/posts/abc';
const otherConcretePath = '/users/456/posts/xyz';
const malformedPath = '/users/{userId/posts';
console.log('--- Parsing ---');
const parsedPath = parse(openApiPath);
console.log('Parsed path:', JSON.stringify(parsedPath, null, 2));
console.log('\n--- Validation ---');
const isValid = validate(openApiPath);
console.log(`Is '${openApiPath}' valid?`, isValid); // true
const isMalformedValid = validate(malformedPath);
console.log(`Is '${malformedPath}' valid?`, isMalformedValid); // false
console.log('\n--- Resolution ---');
const resolvedPath = resolve(openApiPath, { userId: '456', postId: 'def' });
console.log(`Resolved path:`, resolvedPath); // /users/456/posts/def
console.log('\n--- Matching ---');
const matchedParams = match(openApiPath, concretePath);
console.log(`Matched parameters for '${concretePath}':`, matchedParams); // { userId: '123', postId: 'abc' }
const noMatch = match(openApiPath, '/products/1');
console.log(`Matched parameters for '/products/1':`, noMatch); // null
console.log('\n--- Normalization ---');
const normalizedPath = normalize('/users/./profile/../settings');
console.log(`Normalized path:`, normalizedPath); // /users/settings
console.log('\n--- Identity Check ---');
const path1 = '/pets/{petId}';
const path2 = '/pets/{id}';
const path3 = '/pets/{petId}';
console.log(`Is '${path1}' identical to '${path2}'?`, isIdentical(path1, path2)); // false (different parameter names)
console.log(`Is '${path1}' identical to '${path3}'?`, isIdentical(path1, path3)); // true
Debug
Known issues
breakingVersion 2.0.0 introduced significant changes to align the ABNF grammar more strictly with RFC 3986, which can alter how certain path templates are interpreted or validated. This includes refined handling of trailing slashes.fixReview existing path template definitions and validation logic. Ensure your templates are compliant with RFC 3986 standards, particularly regarding trailing slashes and special characters.
affects: >=2.0.0
gotchaThe `validate` function only checks the syntactic correctness of the path templating expression itself, according to the ABNF grammar. It does not validate the existence or correctness of corresponding path parameters within your OpenAPI document's Path Item or Operation objects.fixAlways ensure that every template expression (e.g., `{userId}`) in your OpenAPI paths corresponds to a defined path parameter in the relevant Path Item or Operation object of your OpenAPI specification. affects: >=1.0.0
gotchaThe package's `engines` field specifies a minimum Node.js version of `12.20.0`. Using older Node.js versions might lead to unexpected behavior or compatibility issues.fixEnsure your Node.js environment is updated to version `12.20.0` or newer to guarantee full compatibility and access to modern JavaScript features used by the library.
affects: <12.20.0 (Node.js)
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'parse') OR TypeError: openapi_path_templating_1.parse is not a function
This error typically occurs when attempting to `require` named exports directly from a module designed with ES Modules in mind, or when incorrect destructuring is used in CommonJS.
fixFor ES Modules (recommended in Node.js >=12.20.0 with `"type": "module"` in package.json), use `import { parse } from 'openapi-path-templating';`. For CommonJS, ensure correct destructuring: `const { parse, validate } = require('openapi-path-templating');`. Path does not match template OR match() returns null unexpectedly
Mismatches in trailing slash handling, or subtle differences in path template syntax interpretation, especially following the ABNF grammar changes introduced in v2.0.0, can prevent paths from matching as expected.
fixUpdate `openapi-path-templating` to at least `v2.0.0` to benefit from improved RFC 3986 alignment. Carefully review path template definitions and concrete URLs for consistency in trailing slashes and parameter naming. Also, ensure no special characters are incorrectly encoded.
Parsing error: Unrecognized character in path template OR similar syntax error for seemingly valid templates
Earlier versions (e.g., pre-2.0.1) had minor bugs that could lead to incorrect parsing of specific characters or patterns within path templates, such as the `z` character issue.
fixUpdate the package to version `2.0.1` or newer. This version specifically addresses a bug where template expressions containing the character 'z' were not recognized correctly.
Audit
Dependencies
No dependency data recorded yet.