s2json

About

S2JSON is a format for encoding a variety of geographic data structures that simplifies the GeoJSON spec and builds ontop of it to include S2 Geometry.

Notable features of S2JSON are:

• Properties data is clearly defined on how it can be shaped.
• 🧊 Support for 3D geometries.
• 🏷️ Support for metadata.
• ♏ Support for M-Values for each geometry point.
• 📦 Support for bounding boxes
• 🫥 Updated spec to handle vector structures.
• 🔨 Tools for converting between GeoJSON, S2JSON, and quad-tree Tile structures
• 🪩 Support for S2Feature and S2FeatureCollection types based upon the S2 Geometry spherical projection.
• ♻️ Feature Properties & M-Values are defined in scope to ensure they can be easily processed by lower level languages as structures, but also adds value to other projects down the line.
• 🛑 GeoJSON no longer supports GeometryCollection.
• 📝 Attribution can be added to either a FeatureCollection or S2FeatureCollection

// GeoJSON example
{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [125.6, 10.1]
  },
  "properties": {
    "name": "Dinagat Islands"
  }
}
// GeoJSON Vector example
{
  "type": "VectorFeature",
  "geometry": {
    "type": "Point",
    "coordinates": { x: 125.6, y: 10.1 }
  },
  "properties": {
    "name": "Dinagat Islands"
  }
}
// S2JSON example
{
  "type": "S2Feature",
  "face": 0,
  "geometry": {
    "type": "Point",
    "coordinates": { x: 0.5, y: 0.5 }
  },
  "properties": {
    "name": "Null Island"
  }
}

Read The Spec

s2json-spec

Implementations

• s2-tools

Install

# bun
bun add -D s2json-spec
# pnpm
pnpm add -D s2json-spec
# yarn
yarn add -D s2json-spec
# npm
npm install -D s2json-spec

# cargo
cargo install s2json

grammars/highlighting for VSCode are available for install.

Development

Requirements

You need the tool tarpaulin to generate the coverage report. Install it using the following command:

cargo install cargo-tarpaulin

The bacon coverage tool is used to generate the coverage report. To utilize the pycobertura package for a prettier coverage report, install it using the following command:

pip install pycobertura

Validated Your Data

Note: Be sure to set resolveJsonModule: true in your tsconfig.json to ensure json may be loaded as a module.

import Ajv from 'ajv';
import * as schema from 's2json-spec/s2json.schema.json'; // Path to the schema

import type { Feature } from 's2json-spec';

const ajv = new Ajv();
const validate = ajv.compile(schema);

const feature: Feature = {
  type: 'Feature',
  geometry: {
    type: 'Point',
    coordinates: [125.6, 10.1],
  },
  properties: {
    name: 'Dinagat Islands',
  },
};

validate(feature); // true

Running Tests

To run the tests, use the following command:

# TYPESCRIPT
## basic test
bun run test
## live testing
bun run test:dev

# RUST
## basic test
cargo test
# live testing
bacon test

Generating Coverage Report

To generate the coverage report, use the following command:

cargo tarpaulin
# bacon
bacon coverage # or type `l` inside the tool