Specs via JSON

The CMV specification stores the coordination space (i.e., the state of the views) and defines which views and properties are coordinated.

Optional properties

key

• Type: string

A unique ID for the specification. Optional.

Intended to be used in situations where <CoordinationProvider/> is used as a controlled component (i.e., a parent component is the source of truth for the specification prop and likely also uses the onSpecChange prop). For example, if a change in spec.key is detected, the specification will be re-validated (which might not occur on other changes to specification for performance reasons).

coordinationSpace

• Type: object

The coordination space stores the values associated with each coordination object. It may be helpful to recall that the coordination space is analogous to computer memory which stores values of variables, and the coordination scope names are analogous to references to different locations in memory.

The keys of each object (at the first level) in the coordination space represent coordination types. The keys of each coordination type object represent coordination scope names. The types of values that each coordination scope can take can be as simple as a single number or as complex as an array or object, and depend on the types of values supported by its coordination type.

...,
"coordinationSpace": {
    "embeddingZoom": {
        "EZ1": 2,
        "EZ2": 20
    },
    "embeddingType": {
        "ET1": "UMAP",
        "ET2": "PCA"
    }
},
...

viewCoordination

...,
"viewCoordination": {
    "tsneView": {
        "coordinationScopes": {
            "embeddingType": "ET1",
            "embeddingZoom": "EZ1"
        }
    },
    "umapView": {
        "coordinationScopes": {
            "embeddingType": "ET2",
            "embeddingZoom": "EZ2"
        }
    }
},
...

JSON schema

Show JSON schema

Note that this schema is not very strict:

• No restrictions on coordination type names
• No restrictions on coordination type value schemas
• No restrictions on which coordination scopes can be mapped to views based on their presence in the coordination space

{  "$ref": "#/definitions/spec",  "definitions": {    "spec": {      "type": "object",      "properties": {        "key": {          "type": [            "string",            "number"          ]        },        "coordinationSpace": {          "type": "object",          "additionalProperties": {            "anyOf": [              {                "type": "object",                "additionalProperties": {}              },              {                "type": "null"              }            ]          },          "description": "The coordination space stores the values for each scope of each coordination object."        },        "viewCoordination": {          "type": "object",          "additionalProperties": {            "type": "object",            "properties": {              "coordinationScopes": {                "type": "object",                "additionalProperties": {                  "anyOf": [                    {                      "type": "string"                    },                    {                      "type": "array",                      "items": {                        "type": "string"                      }                    }                  ]                }              },              "coordinationScopesBy": {                "type": "object",                "additionalProperties": {                  "type": "object",                  "additionalProperties": {                    "type": "object",                    "additionalProperties": {                      "$ref": "#/definitions/spec/properties/viewCoordination/additionalProperties/properties/coordinationScopes/additionalProperties"                    }                  }                }              }            },            "additionalProperties": false          },          "description": "The layout array defines the views, or components, rendered in the grid."        }      },      "additionalProperties": false    }  },  "$schema": "http://json-schema.org/draft-07/schema#"}

The JSON schema is published to NPM via @use-coordination/json-schema:

import jsonSchema from '@use-coordination/json-schema/dist/spec.schema.json';

Zod schema

To enforce the coordination values for particular coordination types, we can build a Zod schema:

import { buildSpecSchema, z } from '@use-coordination/schema';

const specSchema = buildSpecSchema({
    someCoordinationType: z.number(),
    someOtherCoordinationType: z.array(z.string()),
});

Integration with type system

We provide a helper function that checks the specification using TypeScript. This can be helpful to check that coordination types and scopes used in the specification are valid.

defineSpec(spec)

Parameters

• spec (object) - A JSON object representing a specification.

Returns

• object - The same spec object that was passed in.

This checks that the coordination types and scopes used within the viewCoordination object are valid due to their presence in the coordinationSpace. Currently, this function is unable to check validity within meta-coordination scope mappings.