The spec for a schema-mapper schema.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs
src
.codeclimate.yml
.gitignore
.npmignore
LICENSE
README.md
esdoc.json
package.json
publish-docs.js
typedefs.js

README.md

schema-mapper-spec

Dependencies License

Schema mapper defines a specification for data and is specifically designed to make storing data in different data stores less painful (especially for the ones that need a schema to be more useful).

It provides:

  • A definition for a Project containing a name, a version and schemas.
  • A definition for a Schema that is easy to write by humans but also easy to parse for computers.
  • A definitions for Changes that describe modifications made to a project.
  • A definition for an Item which describes a format for representing data.
  • A definition for Metadata which describes information about the project and schema that an item belongs to.

A Project groups a bunch of schemas and versions them.

A Schema describes the type of the data and the columns it has.

Changes represent individual modifications to the schema. These changes can be used to transform an Item object from a old version to a newer one or the other way around.

Using the specifications

There are a couple of ways to use this specification.

Validation

npm install --save schema-mapper-validator

Usage:

import validator from 'schema-mapper-validator';

let projectValidationResult = validator.validateProject(project);
let schemaValidationResult = validator.validateSchema(schema);
let changesValidationResult = validator.validateChanges(changes);
let itemValidationResult = validator.validateItem(item);
console.log(projectValidationResult, schemaValidationResult, changesValidationResult, itemValidationResult);

Types

Below is a specification of the types

Projects

Is an object where the key is the id of the project and the value is a Project.

Project

The project is an object that contains:

  • A name property, that will for example be used for determining the name of a database.
  • A version property, that will for example be used for determining the name of a database.
  • A schemas property that contains the schemas of the project.
NameTypeDescription
nameStringThe name of the project
versionNumberThe version of the project
schemasObjectAn object of schemas where the key is the unique id for the schema and the value is an object of type Schema

Schemas

Is an object where the key is the id of the schema and the value is a Schema.

Schema

The schema is an object that contains:

  • A name property, that will for example be used for determining the name of a database table.
  • A columns property that describe the properties of the data.
NameTypeDescription
nameStringThe name of the schema
columnsObjectAn object of columns where the key is the unique id for the column and the value is an object of type Column

Example:

{
  "name": "users",
  "columns": {
    "1": {
      "name": "id",
      "type": "uuid"
    },
    "2": {
      "name": "name",
      "type": "string"
    },
    "3": {
      "name": "email",
      "type": "string"
    },
    "4": {
      "name": "location",
      "type": "point"
    }
  }
}

Columns

Columns describe all the properties of data. It is an object where the key is the id of the column and the value is a Column.

Column

A column describes a single property of data.

NameTypeDescription
nameStringThe name of the column
type String The type of the column, which can be any ColumnType

Example:

{
  "name": "id",
  "type": "uuid"
}

ColumnType

The column type is a string indicating the type of the value in the data. Here is a table to see what a the different types are and what their data format looks like.

Column type JSON type Example
uuid String "583814cd-b90a-4341-8825-ab42d1125666"
uuid[] Array ["583814cd-b90a-4341-8825-ab42d1125666"]
string String "Hello"
string[] Array ["Hello", "World"]
text String "I can be very long"
text[] Array ["It's just text", "Yo!"]
point Object (GeoJSON Point) { "type": "Point", "coordinates": [50, 5] }
point[] Object (GeoJSON MultiPoint) { "type": "MultiPoint", "coordinates": [ [100.0, 0.0], [101.0, 1.0] ] }
linestring Object (GeoJSON LineString) { "type": "LineString", "coordinates": [ [100.0, 0.0], [101.0, 1.0] ] }
linestring[] Object (GeoJSON MultiLineString) { "type": "MultiLineString", "coordinates": [ [ [100.0, 0.0], [101.0, 1.0] ], [ [102.0, 2.0], [103.0, 3.0] ] ] }
polygon Object (GeoJSON Polygon) { "type": "Polygon", "coordinates": [ [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ] ] }
polygon[] Object (GeoJSON MultiPolygon) { "type": "MultiPolygon", "coordinates": [ [[[102.0, 2.0], [103.0, 2.0], [103.0, 3.0], [102.0, 3.0], [102.0, 2.0]]], [[[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]], [[100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2]]] ] }
date String "2015-08-03"
date[] Array ["2015-08-03", "2016-09-04"]
datetime String "2015-08-03 12:42:33"
datetime[] Array ["2015-08-03 12:42:33", "2015-08-03 12:42:49"]
float Number 15.04
float[] Array [14.04, 15.04]
integer Number 420
integer[] Array [1, 2, 3]
boolean Boolean true
boolean[] Array [ true, false ]
json Object { test: true, number: 1 }
json[] Array [{ test: true }, {test: false}]

Item

An item describes a piece of data. The keys map to a Column's name and the value maps to the JSON value of it's ColumnType.

Metadata

Metadata describes information about the project and schema. It is attached to the item under the _meta key.

NameTypeDescription
projectIdStringA string indicating the id of the project
projectNameStringA string indicating the name of the project
projectVersionNumberA string indicating the version of the project
schemaIdStringA string indicating the id of the schema
schemaNameStringA string indicating the name of the schema
primaryObjectThe primary column

Example:

{
  "projectId": "1",
  "projectName": "demo",
  "projectVersion": 3,
  "schemaId": "1",
  "schemaName": "users",
  "primary": {
    "name": "id",
    "type": "uuid"
  }
}

Changes

Changes describe modifications made to a Project. The data format is a simple array, containing a combination of the changes described below.

ProjectCreateChange

This change indicates that a project should be created

NameTypeDescription
changeStringA string indicating the type of change
projectIdStringThe id of the project
projectStringA Project

Example:

{
  "change": "project.create",
  "projectId": "0",
  "project": {
    "name": "demo",
    "version": 0,
    "schemas": {
      "1": {
        "name": "users",
        "columns": {
          "1": {
            "name": "id",
            "type": "uuid"
          }
        }
      }
    }
  }
}

ProjectTagChange

This change indicates that a project's version should be increased to the version provided in the change.

NameTypeDescription
changeStringA string indicating the type of change
projectIdStringThe id of the project
versionNumberA The new project version

Example:

{
  "change": "project.tag",
  "projectId": "0",
  "version": 1
}

ProjectRenameChange

This change indicates that the name of a project should change.

NameTypeDescription
changeStringA string indicating the type of change
projectIdStringThe id of the project
nameStringA The new name for the project

Example:

{
  "change": "project.rename",
  "projectId": "0",
  "name": "newname"
}

ProjectRemoveChange

This change indicates that a project should be removed.

NameTypeDescription
changeStringA string indicating the type of change
projectIdStringThe id of the project to remove

Example:

{
  "change": "project.remove",
  "projectId": "0"
}

SchemaCreateChange

This change indicates that a schema is created.

NameTypeDescription
changeStringA string indicating the type of change
projectIdStringThe id of the project
schemaIdStringThe id of the schema
schemaStringA Schema

Example:

{
  "change": "schema.create",
  "projectId": "1",
  "schemaId": "1",
  "schema": {
    "name": "users",
    "columns": {
      "1": {
        "name": "id",
        "type": "uuid"
      }
    }
  }
}

SchemaRemoveChange

This change indicates that a schema is removed.

NameTypeDescription
changeStringA string indicating the type of change
projectIdStringThe id of the project
schemaIdStringThe id of the schema

Example:

{
  "change": "schema.remove",
  "schemaId": "1"
}

SchemaRenameChange

This change indicates that a schema is renamed.

NameTypeDescription
changeStringA string indicating the type of change
schemaIdStringThe id of the schema
nameStringThe name of the schema

Example:

{
  "change": "schema.rename",
  "schemaId": "1",
  "name": "users"
}

ColumnCreateChange

This change indicates that a column is added to a schema.

NameTypeDescription
changeStringA string indicating the type of change
schemaIdStringThe id of the schema
columnIdStringThe id for the column
columnStringThe properties of the Column

Example:

{
  "change": "column.create",
  "schemaId": "1",
  "columnId": "1",
  "column": {
    "name": "id",
    "type": "uuid"
  }
}

ColumnRemoveChange

This change indicates that a column is removed from a schema.

NameTypeDescription
changeStringA string indicating the type of change
schemaIdStringThe id of the schema
columnIdStringThe id for the column
oldColumnNameStringThe name for the column that is removed

Example:

{
  "change": "column.remove",
  "schemaId": "1",
  "columnId": "2",
  "oldColumnName": "email"
}

ColumnRenameChange

This change indicates that a column is removed from a schema.

NameTypeDescription
schemaIdStringThe id of the schema
changeStringA string indicating the type of change
columnIdStringThe id for the column
nameStringThe new name of the column
oldNameStringThe old name of the column

Example:

{
  "change": "column.rename",
  "schemaId": "1",
  "columnId": "1",
  "name": "id"
}

ColumnTypechangeChange

This change indicates that the type of a column is changed.

NameTypeDescription
changeStringA string indicating the type of change
schemaIdStringThe id of the schema
columnIdStringThe id for the column
columnNameStringThe name of the column
typeStringThe new type of the column

Example:

{
  "change": "column.typechange",
  "schemaId": "1",
  "columnId": "1",
  "type": "integer"
}

API docs

API Docs

Licence

MIT