Registry / serialization / vega-schema-url-parser

vega-schema-url-parser

library3.0.2jsnpmunverified

The `vega-schema-url-parser` package provides a utility function designed to extract the library type (either "vega" or "vega-lite") and its corresponding version number from a given Vega or Vega-Lite JSON schema URL. This functionality is crucial for applications that programmatically need to identify and validate Vega/Vega-Lite specifications, as the `$schema` field in these specifications often points to URLs like `https://vega.github.io/schema/vega-lite/v5.json` or `https://vega.github.io/schema/vega/v5.19.0.json`. The parser simplifies the process of interpreting these schema URLs, making it easier for tools such as `vega-embed` to determine the correct rendering or parsing mode, and for development environments to offer accurate schema validation and autocompletion features. The current stable version is 3.0.2, with its release cadence generally aligning with major updates to the broader Vega and Vega-Lite ecosystems. Its key differentiator is its highly focused purpose, offering a reliable and standardized method for interpreting schema URLs without requiring complex manual string manipulation, which is a common footgun for developers parsing these URLs directly.

serialization data

npm install vega-schema-url-parser

github ↗package ↗

INSTALL

IMPORT

SIG · VEGA-SCHEMA-URL-PA

vega-schema-url-parser

serializationjavascriptv3.0.2

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.

parseSchemaUrl

✓ import parseSchemaUrl from 'vega-schema-url-parser';

✗ const parseSchemaUrl = require('vega-schema-url-parser');

The library primarily exports a default function. Direct CommonJS `require()` might not work as expected in mixed environments; prefer ESM `import`.

ParsedSchema

✓ import type { ParsedSchema } from 'vega-schema-url-parser';

Type import for the return value of `parseSchemaUrl` ( `{ library: 'vega' | 'vega-lite' | null; version: string | null; }`).

parseSchemaUrl (browser global)

✓ const parseSchemaUrl = vegaSchemaUrlParser.default;

When used as a global in a browser environment after script inclusion, the function might be available under a namespace like `vegaSchemaUrlParser`.

This quickstart demonstrates how to use the `parseSchemaUrl` function to extract the library type and version from various valid Vega and Vega-Lite schema URLs, as well as how it gracefully handles malformed or unrecognized inputs by returning `null` values.

import parseSchemaUrl from 'vega-schema-url-parser'; // Example Vega-Lite schema URL with a major version const vegaLiteSchemaUrl = 'https://vega.github.io/schema/vega-lite/v5.json'; const parsedVegaLite = parseSchemaUrl(vegaLiteSchemaUrl); console.log('Parsed Vega-Lite Schema:', parsedVegaLite); // Expected output: { library: 'vega-lite', version: '5' } // Example Vega schema URL with an exact version const vegaSchemaUrl = 'https://vega.github.io/schema/vega/v5.19.0.json'; const parsedVega = parseSchemaUrl(vegaSchemaUrl); console.log('Parsed Vega Schema:', parsedVega); // Expected output: { library: 'vega', version: '5.19.0' } // Example of an unrecognized or malformed URL const malformedUrl = 'https://example.com/not-a-vega-schema.json'; const parsedMalformed = parseSchemaUrl(malformedUrl); console.log('Parsed Malformed URL:', parsedMalformed); // Expected output: { library: null, version: null } // Example with an invalid string input (TypeScript will flag this, but useful for JS environments) // In a robust application, you'd typically validate input beforehand. const invalidStringInput = 'just some random string'; const parsedInvalidString = parseSchemaUrl(invalidStringInput); console.log('Parsed Invalid String Input:', parsedInvalidString); // Expected output: { library: null, version: null }

Debug

Known issues

breakingAs part of the broader Vega ecosystem's transition, `vega-schema-url-parser` in its current major versions (like 3.x) is likely distributed as an ESM-only package. This means that direct `require()` statements in CommonJS modules may lead to runtime errors or require specific build tool configurations to resolve correctly.

fix

Migrate to ESM `import` statements (e.g., `import parseSchemaUrl from 'vega-schema-url-parser';`) or configure your build system (e.g., Webpack, Rollup, Node.js `--experimental-loader`) to handle ESM imports in CJS contexts.

affects: >=3.0.0

gotchaThe `parseSchemaUrl` function returns `null` for both `library` and `version` fields if the provided URL does not conform to the expected Vega or Vega-Lite schema URL format. It does not throw an error for unrecognized formats.

fix

Always check the `library` and `version` properties of the returned object for `null` before attempting to use them, especially with user-provided URLs. Example: `const { library, version } = parseSchemaUrl(url); if (library && version) { /* use them */ }`

affects: >=1.0.0

gotchaThe parser extracts the *explicitly specified* version from the URL (e.g., 'v2', 'v5.0', 'v5.2.0'). It does *not* resolve partial versions (like `v2`) to the latest full version (e.g., `v2.6.5`), even though the Vega schema server might redirect `https://vega.github.io/schema/vega/v2.json` to `v2.6.5.json`. The output will be '2', not '2.6.5'.

fix

If you need the *resolved* latest version for a major/minor schema URL, you would typically need to fetch the content of the `$schema` URL and inspect the actual schema for its full version, or consult the Vega/Vega-Lite documentation for version mappings. This parser provides the version as it appears in the URL path.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: parseSchemaUrl is not a function

Attempting to use `require('vega-schema-url-parser')` as a callable function in a CommonJS module when the package is ESM-only, or importing a named export incorrectly.

fix

Use ESM syntax: `import parseSchemaUrl from 'vega-schema-url-parser';`. If in Node.js CJS, you might need dynamic import `const { default: parseSchemaUrl } = await import('vega-schema-url-parser');` or configure Node.js to handle ESM.

TS2349: This expression is not callable. Type 'typeof import(".../node_modules/vega-schema-url-parser/index")' has no construct signatures.

In TypeScript, attempting to call the module itself (`import * as parseSchemaUrl from '...'`) rather than its default export.

fix

Ensure you are importing the default export correctly: `import parseSchemaUrl from 'vega-schema-url-parser';`

Cannot find name 'parseSchemaUrl'.

Incorrectly trying to use the function without an import statement in a module environment, or a global variable name collision.

fix

Add the necessary import statement: `import parseSchemaUrl from 'vega-schema-url-parser';` at the top of your file.

Upgrade

Version history

3.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vega/schema ↗

packagehttps://www.npmjs.com/package/vega-schema-url-parser ↗