{"id":11496,"library":"openapi-server-url-templating","title":"OpenAPI Server URL Templating","description":"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.","status":"active","version":"1.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/swaggerexpert/openapi-server-url-templating","tags":["javascript","openapi","server","url","templating","parser","validator","substitution","typescript"],"install":[{"cmd":"npm install openapi-server-url-templating","lang":"bash","label":"npm"},{"cmd":"yarn add openapi-server-url-templating","lang":"bash","label":"yarn"},{"cmd":"pnpm add openapi-server-url-templating","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses ES modules. While CommonJS `require` might work in some transpiled environments, direct ESM import is recommended.","wrong":"const { parse } = require('openapi-server-url-templating');","symbol":"parse","correct":"import { parse } from 'openapi-server-url-templating';"},{"note":"This is a named export for URL template validation.","wrong":"import validate from 'openapi-server-url-templating';","symbol":"validate","correct":"import { validate } from 'openapi-server-url-templating';"},{"note":"Used for replacing variables in a parsed URL template with provided values.","wrong":"const substitute = require('openapi-server-url-templating').substitute;","symbol":"substitute","correct":"import { substitute } from 'openapi-server-url-templating';"},{"note":"This symbol is a TypeScript type, not a runtime value. Use `import type`.","wrong":"import { Grammar } from 'openapi-server-url-templating';","symbol":"Grammar","correct":"import type { Grammar } from 'openapi-server-url-templating';"}],"quickstart":{"code":"import { parse, validate, substitute } from 'openapi-server-url-templating';\n\nconst urlTemplate = 'https://{username}.gigantic-server.com:{port}/{basePath}';\n\n// 1. Parse the URL template\nconst parseResult = parse(urlTemplate);\nconsole.log('Parse Success:', parseResult.result.success);\n\n// 2. Define server variables for validation and substitution\nconst serverVariables = {\n  username: { default: 'demo', enum: ['demo', 'admin'] },\n  port: { default: '8443', enum: ['8443', '443'] },\n  basePath: { default: 'v2', enum: ['v1', 'v2'] }\n};\n\n// 3. Validate the URL template with variables\nconst validationResult = validate(urlTemplate, serverVariables);\nconsole.log('Validation Success:', validationResult.result.success);\n\n// 4. Substitute variables to get the final URL\nconst values = { username: 'admin', port: '443', basePath: 'v1' };\nconst substitutedUrl = substitute(urlTemplate, serverVariables, values);\nconsole.log('Substituted URL:', substitutedUrl); // Expected: https://admin.gigantic-server.com:443/v1\n\n// Example with default values\nconst substitutedUrlWithDefaults = substitute(urlTemplate, serverVariables, {});\nconsole.log('Substituted URL (defaults):', substitutedUrlWithDefaults); // Expected: https://demo.gigantic-server.com:8443/v2","lang":"typescript","description":"Demonstrates parsing, validating, and substituting an OpenAPI server URL template using defined server variables and supplied values, including usage of default values."},"warnings":[{"fix":"Ensure your OpenAPI server URL templates strictly adhere to the OpenAPI Specification's ANBF grammar to guarantee consistent parsing and validation.","message":"The 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.","severity":"breaking","affected_versions":">=1.3.0"},{"fix":"Upgrade to version 1.1.0 or newer to avoid potential module resolution problems, especially in bundlers or specific Node.js setups.","message":"Prior 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.","severity":"gotcha","affected_versions":"<1.1.0"},{"fix":"Always provide a complete `serverVariables` object that includes definitions (even with just a `default` property) for every variable expected in your URL templates.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"TypeError: (0 , openapi_server_url_templating__WEBPACK_IMPORTED_MODULE_0__.parse) is not a function"},{"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.","cause":"The input URL template string does not conform to the expected OpenAPI server URL templating grammar, preventing successful parsing.","error":"GrammarError: no parse tree"},{"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.","cause":"The `validate` or `substitute` function was called with a URL template containing a variable that was not present in the provided `serverVariables` object.","error":"Error: Variable 'someVar' is not defined in server variables."}],"ecosystem":"npm"}