bl-json-validator

Repository contains JS validation tool and set of schema files. Validation tool idea is to check JSON validity for different templates. Front-end clients should comply with schemas provided in this repo. If JSON passes the validation, such JSON should be working on clients and should not cause crashes.

Schema folder contains yaml files which defines correct JSON structure for different templates.

Installation

To install bl-json-validator, use npm:

npm install bl-json-validator

Usage

To use bl-json-validator in your project:

import { BLValidateJSON, GetSchemaUrls } from 'bl-json-validator';

// Validate a JSON
const jsonData = { /* your JSON here */ };
const overlayName = 'issov2';
const result = await BLValidateJSON(jsonData, overlayName);

console.log(result);

// Get schema URLs
const schemaUrls = GetSchemaUrls();
console.log(schemaUrls);

Functionality

BLValidateJSON

The main function BLValidateJSON takes two parameters:

1. jsonData: The JSON to be validated.
2. overlayName: The name of the overlay for which the JSON is being validated.

Valid values for overlayName are:

• 'issov2'
• 'trivia'
• 'conversionv1'
• 'conversionv2'
• 'ctfs2'
• 'isso'
• 'dynamic_carousel'
• 'selector_with_isso'
• 'store_locator'
• 'image_gallery'
• 'video_gallery'

The function validates the JSON by comparing it with a YAML file associated with the overlayName. The validation result will include:

• Errors: Critical issues indicating that the JSON does not comply with the schema.
• Warnings: Suggestions or minor issues that do not invalidate the JSON but could be improved.

Multiple Platforms

Some overlays have multiple platforms:

• "isso" has platforms: default, tvos, and roku
• "ctfs2" has platforms: default and RAF

The library will automatically validate the JSON on all applicable platforms and provide a report for each.

GetSchemaUrls

The GetSchemaUrls function returns the URLs of the YAML schemas used for validation.

Examples

import { BLValidateJSON } from 'bl-json-validator';

const jsonData = {
  // Your JSON here
};

const result = await BLValidateJSON(jsonData, 'issov2');

if (result.errors.length === 0) {
  console.log("The JSON is valid for ISSO V2");
} else {
  console.log("Errors found:", result.errors);
}

if (result.warnings.length > 0) {
  console.log("Warnings:", result.warnings);
}

You can check our online validation tool that uses this library.

Build and Distribution

The library is built using Rollup to provide different distribution formats:

Build Process

To build the library:

npm run build

This will generate three different builds in the dist directory:

1. ESM (ECMAScript Modules) - dist/index.esm.js

   • Modern format for ES6-compatible environments
   • Used when importing with import statements
   • Ideal for modern web applications and bundlers

2. UMD (Universal Module Definition) - dist/index.umd.js

   • Compatible with browsers (global scope), AMD, and CommonJS
   • Minified for browser use
   • Can be included directly in HTML via <script> tag

3. CommonJS - dist/index.cjs.js

   • Traditional Node.js format
   • Used when importing with require()
   • Ideal for Node.js applications

Usage in Different Environments

In Node.js (CommonJS)

const { BLValidateJSON } = require('bl-json-validator');

In Modern JavaScript (ESM)

import { BLValidateJSON } from 'bl-json-validator';

In Browser (UMD)

<!-- Using CDN -->
<script src="https://unpkg.com/bl-json-validator"></script>
<script>
  const { BLValidateJSON } = window.BLJsonValidator;
</script>

<!-- Or local file -->
<script src="./node_modules/bl-json-validator/dist/index.umd.js"></script>

Dependencies

The library has two main dependencies:

• isomorphic-fetch: For making HTTP requests in both Node.js and browser environments
• js-yaml: For YAML parsing and schema validation

These dependencies are marked as external and should be installed separately when using the library in Node.js. In browser environments, ensure these dependencies are loaded before loading the library:

<script src="https://unpkg.com/js-yaml/dist/js-yaml.min.js"></script>
<script src="https://unpkg.com/isomorphic-fetch/fetch-npm-browserify.js"></script>
<script src="https://unpkg.com/bl-json-validator"></script>

The build process uses Rollup with the following plugins:

• @rollup/plugin-node-resolve: Resolves node_modules dependencies
• @rollup/plugin-commonjs: Converts CommonJS modules to ES6
• @rollup/plugin-json: Allows importing JSON files
• @rollup/plugin-terser: Minifies the UMD build