Registry / database / jsonschema-bigquery

jsonschema-bigquery

JSON →
library7.0.2jsnpmunverified

Convert JSON Schema (draft-07 or later) into Google BigQuery schema and create or patch tables. Current stable version 7.0.2, released 2023-06-30. Node >=12 required. Lightweight, no runtime dependencies. Key differentiator: direct CLI (jsbq) and embedded API for programmatic schema conversion, with options to prevent additional properties and continue on error. Respects JSON Schema concepts like required fields, enums, and nested objects; maps JSON Schema types to BigQuery types (STRING, INTEGER, FLOAT, BOOLEAN, TIMESTAMP, DATE, TIME, DATETIME, RECORD, REPEATED). Handles complex nested structures and arrays. Supports --preventAdditionalObjectProperties and --continueOnError flags. Integrates with bq CLI for advanced table options. Not actively maintained recently but stable.

databasedevops
npm install jsonschema-bigquery
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · JSONSCHEMA-BIGQUER
J
jsonschema-bigquery
databasejavascriptv7.0.2
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

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

run
✓ import { run } from 'jsonschema-bigquery'
✗ const jsonSchemaBigquery = require('jsonschema-bigquery'); const bigquerySchema = jsonSchemaBigquery.run(jsonSchemaObject, options);
The package is primarily used via require() in CommonJS, but since v7 it also supports ESM imports. The exported function is 'run', not default export.
default (commonjs)
✓ const jsbq = require('jsonschema-bigquery'); const schema = jsbq.run(input, opts);
✗ const { run } = require('jsonschema-bigquery');
CommonJS require returns an object with a 'run' property. Destructuring { run } works too, but beware of TypeScript types.
CLI jsbq
✓ npx jsbq -j schema.json > bigquery_schema.json
✗ jsbq -p myproject -d mydataset -j schema.json
CLI flags: -p, -d, -j, --preventAdditionalObjectProperties, --continueOnError. If you accidentally include -p without -d, it will error.

Converts a JSON Schema object into a BigQuery schema array, handling nested objects and arrays.

const jsbq = require('jsonschema-bigquery'); const input = { $schema: 'http://json-schema.org/draft-07/schema#', type: 'object', properties: { name: { type: 'string' }, age: { type: 'integer' }, email: { type: 'string', format: 'email' }, address: { type: 'object', properties: { street: { type: 'string' }, city: { type: 'string' } }, required: ['street'] }, tags: { type: 'array', items: { type: 'string' } } }, required: ['name'] }; const options = { preventAdditionalObjectProperties: true, continueOnError: false }; const bigquerySchema = jsbq.run(input, options); console.log(JSON.stringify(bigquerySchema, null, 2)); // Outputs BigQuery schema array with fields: name, age, email, address (RECORD), tags (REPEATED)
Debug
Known issues
gotchaInput JSON schema must be dereferenced (no external $refs). The package does not resolve references.
fix
Use a library like json-schema-ref-parser to dereference before passing to jsonschema-bigquery.
affects: all
gotchaCLI requires both -p and -d flags when creating/patching tables. Missing either causes an error.
fix
Always provide project (-p) and dataset (-d) when using jsbq to interact with BigQuery.
affects: all
breakingVersion 7.0.0 changed the main export from a factory function to a module with a 'run' method.
fix
Update code from const jsbq = require('jsonschema-bigquery')(options) to const jsbq = require('jsonschema-bigquery'); const schema = jsbq.run(input, options);
affects: >=7.0.0
deprecatedThe --createTable and --patchTable flags were removed in v5; use bq CLI instead.
fix
Use bq mk --schema=... or bq update --schema=... as shown in README.
affects: >=5.0.0
gotchaFormat fields like 'email', 'date-time' are ignored; BigQuery doesn't support them natively.
fix
Handle format validation separately or use string type with constraints.
affects: all
Errors
Common errors & fixes
Error: Invalid JSON schema: Unresolved $ref
Input schema contains external $ref pointers that are not resolved.
fix
Dereference the schema first using json-schema-ref-parser: Schema = await $ref.dereference(schema)
TypeError: jsbq.run is not a function
Using older require pattern from pre-v7.
fix
Update to const jsbq = require('jsonschema-bigquery'); then jsbq.run(input).
Error: Missing required flag: -p
CLI used without -p (project) when -d is provided.
fix
Provide both -p and -d flags or use -j only for schema generation.
Upgrade
Version history
7.0.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
6 hits · last 30 days
node
4
Amazon
1
Bingbot
1
Resources
githubhttps://github.com/thedumbterminal/jsonschema-bigquery ↗
packagejsonschema-bigquery ↗
homepagehttps://github.com/thedumbterminal/jsonschema-bigquery#readme ↗
jsonschema-bigquery — npm install jsonschema-bigquery · libregistry