/iglu-javascript-client

Browser JavaScript client for Iglu

Primary LanguageJavaScriptApache License 2.0Apache-2.0

Javascript Iglu Client

early-release Build Status License Release

Snowplow is a scalable open-source platform for rich, high quality, low-latency data collection. It is designed to collect high quality, complete behavioral data for enterprise business.

To find out more, please check out the Snowplow website and our documentation.

Javascript Iglu Client Overview

Iglu is a machine-readable, open-source schema registry for JSON and Thrift schema from the team at Snowplow Analytics.

The JavaScript Iglu client aids validation of schematized JavaScript objects backed by an Iglu-compatible schema service.

Quick start

let client = new IgluClient({
  repositories: [
    {
      "name": "Iglu Central",
      "vendorPrefixes": [
        "com.snowplowanalytics"
      ],
      "connection": {
        "http": {
          "uri": "https://s3.amazonaws.com/iglucentral.com"
        }
      },
      "priority": 1
    }
  ]
});

client.validateObject(obj).then(
    (success) => console.log("Succes:", success)
).catch(
    (failure) => console.log("Fail:", failure)
);

From within a browser you can do something like this:

  <script src="/javascripts/service-workers/snowplow/snowplow-worker-client.js"></script>
  <script src="/javascripts/service-workers/snowplow/init-snowplow-worker.js"></script>

See the init-snowplow-worker.js file in examples/service-worker.

Note

As currently formulated, this client is meant to be used in a ServiceWorker context. Refactoring is needed to separate parts of this system that rely on browser-based API's from those that don't. Notably these are the mechanisms for actually fetching schemas from a remote host and caching those schemas locally.

At the moment the Iglu JavaScript Client is under beta status. There are several points to address before we consider it production-ready, such as:

  • Refactor the fetch/cache mechanism to make it a bit more flexible.
  • Refactor resolver construction to allow easier addition of new resolver types.
  • Add example usage for ServiceWorker as well as Node contexts.
  • Add tests

Architecture

  • The library is written using ES2015. No attempt has been made to make this compatible with previous versions of JS.
  • The client is set up to be asyncronous in operation using Promises.
  • There are three main components:
    • IgluClient: The main entry point to the library. Instances of this class traverse a schematized object hierarchy and validate constituent parts of an object using Schema.
    • Schema: Schema is a class representing a JSON Schema. It can validate a single object but does not traverse an hierarchy.
    • Resolver: A class meant to dereference a schema key/name to an actual schema. Currently only HTTPS-accessible Iglu servers are supported. Resolver also relies on a retrieverFunction that actually handles getting the schema and potentially caching the result.

Contributing

Feedback and contributions are welcome - if you have identified a bug, please log an issue on this repo. For all other feedback, discussion or questions please open a thread on our discourse forum.

Copyright and license

The Snowplow Iglu JavaScript Client is copyright 2016-2022 Snowplow Analytics Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.