Registry / http-networking / openapi-server-url-templating

openapi-server-url-templating

library1.3.0jsnpmunverified

The `openapi-server-url-templating` library provides a robust, specification-compliant mechanism for parsing, validating, and performing substitutions on server URLs as defined within the OpenAPI Specification. It comprehensively supports server URL templating features, including Server Variables, across various OpenAPI versions from 3.0.0 through 3.1.1. The current stable version is 1.3.0, released in December 2024, indicating an active development and maintenance cadence. A key differentiator is its foundational role in establishing the official ABNF grammar for Server URL Templating within the OpenAPI Specification itself, which ensures a high degree of fidelity and accuracy to the standard. The library leverages `apg-lite` for its underlying parsing and validation capabilities, offering a reliable tool for developers working with OpenAPI definitions.

http-networking serialization

npm install openapi-server-url-templating

github ↗package ↗

INSTALL

IMPORT

SIG · OPENAPI-SERVER-URL

openapi-server-url-templating

http-networkingjavascriptv1.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ import { parse } from 'openapi-server-url-templating';

✗ const { parse } = require('openapi-server-url-templating');

The library primarily uses ES modules. While CommonJS `require` might work in some transpiled environments, direct ESM import is recommended.

validate

✓ import { validate } from 'openapi-server-url-templating';

✗ import validate from 'openapi-server-url-templating';

This is a named export for URL template validation.

substitute

✓ import { substitute } from 'openapi-server-url-templating';

✗ const substitute = require('openapi-server-url-templating').substitute;

Used for replacing variables in a parsed URL template with provided values.

Grammar

✓ import type { Grammar } from 'openapi-server-url-templating';

✗ import { Grammar } from 'openapi-server-url-templating';

This symbol is a TypeScript type, not a runtime value. Use `import type`.

Demonstrates parsing, validating, and substituting an OpenAPI server URL template using defined server variables and supplied values, including usage of default values.

import { parse, validate, substitute } from 'openapi-server-url-templating'; const urlTemplate = 'https://{username}.gigantic-server.com:{port}/{basePath}'; // 1. Parse the URL template const parseResult = parse(urlTemplate); console.log('Parse Success:', parseResult.result.success); // 2. Define server variables for validation and substitution const serverVariables = { username: { default: 'demo', enum: ['demo', 'admin'] }, port: { default: '8443', enum: ['8443', '443'] }, basePath: { default: 'v2', enum: ['v1', 'v2'] } }; // 3. Validate the URL template with variables const validationResult = validate(urlTemplate, serverVariables); console.log('Validation Success:', validationResult.result.success); // 4. Substitute variables to get the final URL const values = { username: 'admin', port: '443', basePath: 'v1' }; const substitutedUrl = substitute(urlTemplate, serverVariables, values); console.log('Substituted URL:', substitutedUrl); // Expected: https://admin.gigantic-server.com:443/v1 // Example with default values const substitutedUrlWithDefaults = substitute(urlTemplate, serverVariables, {}); console.log('Substituted URL (defaults):', substitutedUrlWithDefaults); // Expected: https://demo.gigantic-server.com:8443/v2

Debug

Known issues

breakingThe grammar used for parsing and validating URL templates was aligned with the official OpenAPI Specification. While this improves correctness, it might lead to different parsing outcomes for malformed or non-standard templates that might have been accepted by earlier versions.

fix

Ensure your OpenAPI server URL templates strictly adhere to the OpenAPI Specification's ANBF grammar to guarantee consistent parsing and validation.

affects: >=1.3.0

gotchaPrior to v1.1.0, some environments might have experienced issues with module resolution due to the package's `imports` field configuration. This was fixed to improve compatibility.

fix

Upgrade to version 1.1.0 or newer to avoid potential module resolution problems, especially in bundlers or specific Node.js setups.

affects: <1.1.0

gotchaWhen using `validate` or `substitute`, ensure that all variables present in the URL template `{likeThis}` are defined in the `serverVariables` object. Undefined variables will cause validation to fail or substitution to result in unexpected output.

fix

Always provide a complete `serverVariables` object that includes definitions (even with just a `default` property) for every variable expected in your URL templates.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: (0 , openapi_server_url_templating__WEBPACK_IMPORTED_MODULE_0__.parse) is not a function

This typically indicates a mismatch between CommonJS `require` and ES module `import` syntax, often encountered in Webpack or similar bundler environments that misinterpret the module type.

fix

Ensure your project is configured to correctly handle ES modules. If using TypeScript, check `tsconfig.json` `module` and `moduleResolution` settings. For JavaScript, verify your bundler's configuration or explicitly use ESM imports in a module-aware context.

GrammarError: no parse tree

The input URL template string does not conform to the expected OpenAPI server URL templating grammar, preventing successful parsing.

fix

Review the URL template for syntax errors, missing braces (`{`, `}`), or invalid characters according to the OpenAPI Specification's Server Object URL rules. Refer to the `parseResult` object for detailed error messages.

Error: Variable 'someVar' is not defined in server variables.

The `validate` or `substitute` function was called with a URL template containing a variable that was not present in the provided `serverVariables` object.

fix

Add a definition for `someVar` to your `serverVariables` object, even if it's just `someVar: { default: 'defaultValue' }`. All templated variables must have a corresponding entry.

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/swaggerexpert/openapi-server-url-templating ↗

packagehttps://www.npmjs.com/package/openapi-server-url-templating ↗