@thomasfosterau/charts 0.0.0-stage → 0.1.0

package/schema/chart-spec.v1.json

@@ -0,0 +1,393 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/thomasfosterau/components/blob/trunk/packages/charts/schema/chart-spec.v1.json",
+  "$ref": "#/$defs/ChartSpec",
+  "$defs": {
+    "SpecVersion": {
+      "type": "string",
+      "enum": [
+        "1",
+        "1.1"
+      ],
+      "description": "The portable chart spec version this document conforms to."
+    },
+    "Mark": {
+      "type": "string",
+      "enum": [
+        "bar",
+        "line",
+        "point",
+        "area",
+        "tree"
+      ],
+      "description": "The mark (geometric primitive) used to render the chart. The native-charting intersection, plus \"tree\" (spec 1.1): a hierarchy laid out by the interpreter."
+    },
+    "FieldType": {
+      "type": "string",
+      "enum": [
+        "quantitative",
+        "ordinal",
+        "nominal",
+        "temporal"
+      ],
+      "description": "The declared type of an encoded field. Interpreters reconstruct typed values from this declaration, never by sniffing JSON values."
+    },
+    "Channel": {
+      "type": "object",
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "The name of the field in each datum that this channel reads."
+        },
+        "type": {
+          "$ref": "#/$defs/FieldType"
+        }
+      },
+      "required": [
+        "field",
+        "type"
+      ],
+      "additionalProperties": false,
+      "description": "A field-to-channel mapping with an explicit declared type."
+    },
+    "Channel_1": {
+      "type": "object",
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "The name of the field in each datum that this channel reads."
+        },
+        "type": {
+          "$ref": "#/$defs/FieldType"
+        }
+      },
+      "required": [
+        "field",
+        "type"
+      ],
+      "additionalProperties": false,
+      "description": "Spec 1.1: the end of a range on x. With mark \"bar\", each bar spans x to x2. Same type as x, quantitative or temporal."
+    },
+    "Channel_2": {
+      "type": "object",
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "The name of the field in each datum that this channel reads."
+        },
+        "type": {
+          "$ref": "#/$defs/FieldType"
+        }
+      },
+      "required": [
+        "field",
+        "type"
+      ],
+      "additionalProperties": false,
+      "description": "Spec 1.1: the end of a range on y. With mark \"bar\", each bar spans y to y2. Same type as y, quantitative or temporal."
+    },
+    "Channel_3": {
+      "type": "object",
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "The name of the field in each datum that this channel reads."
+        },
+        "type": {
+          "$ref": "#/$defs/FieldType"
+        }
+      },
+      "required": [
+        "field",
+        "type"
+      ],
+      "additionalProperties": false,
+      "description": "Spec 1.1, mark \"tree\": the field naming each row; ids are unique."
+    },
+    "Channel_4": {
+      "type": "object",
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "The name of the field in each datum that this channel reads."
+        },
+        "type": {
+          "$ref": "#/$defs/FieldType"
+        }
+      },
+      "required": [
+        "field",
+        "type"
+      ],
+      "additionalProperties": false,
+      "description": "Spec 1.1, mark \"tree\": the field holding the parent row's id; null (or absent) for a root."
+    },
+    "Channel_5": {
+      "type": "object",
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "The name of the field in each datum that this channel reads."
+        },
+        "type": {
+          "$ref": "#/$defs/FieldType"
+        }
+      },
+      "required": [
+        "field",
+        "type"
+      ],
+      "additionalProperties": false,
+      "description": "Spec 1.1, mark \"tree\": the text of each node; defaults to its id."
+    },
+    "Encoding": {
+      "type": "object",
+      "properties": {
+        "x": {
+          "$ref": "#/$defs/Channel"
+        },
+        "y": {
+          "$ref": "#/$defs/Channel"
+        },
+        "x2": {
+          "$ref": "#/$defs/Channel_1"
+        },
+        "y2": {
+          "$ref": "#/$defs/Channel_2"
+        },
+        "id": {
+          "$ref": "#/$defs/Channel_3"
+        },
+        "parent": {
+          "$ref": "#/$defs/Channel_4"
+        },
+        "label": {
+          "$ref": "#/$defs/Channel_5"
+        },
+        "color": {
+          "$ref": "#/$defs/Channel"
+        },
+        "size": {
+          "$ref": "#/$defs/Channel"
+        },
+        "opacity": {
+          "$ref": "#/$defs/Channel"
+        }
+      },
+      "additionalProperties": false,
+      "description": "Field-to-channel mappings describing how data maps to visual channels."
+    },
+    "DatumValue": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "number"
+        },
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "A single value inside a data row: a flat JSON primitive."
+    },
+    "Datum": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/DatumValue"
+      },
+      "description": "A single data row: a flat record of JSON primitives."
+    },
+    "InlineData": {
+      "type": "object",
+      "properties": {
+        "values": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Datum"
+          }
+        }
+      },
+      "required": [
+        "values"
+      ],
+      "additionalProperties": false,
+      "description": "Inline data: small datasets embedded directly in the spec."
+    },
+    "DataRefKind": {
+      "type": "string",
+      "enum": [
+        "query",
+        "node",
+        "url"
+      ],
+      "description": "The kind of external data reference: a live query, another content node, or a URL."
+    },
+    "DataRef": {
+      "type": "object",
+      "properties": {
+        "ref": {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "$ref": "#/$defs/DataRefKind"
+            },
+            "id": {
+              "type": "string",
+              "description": "Identifier of the referenced dataset (query id, node id, or URL)."
+            }
+          },
+          "required": [
+            "kind",
+            "id"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ref"
+      ],
+      "additionalProperties": false,
+      "description": "A reference to an externally stored dataset, resolved by the host."
+    },
+    "Data": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/InlineData"
+        },
+        {
+          "$ref": "#/$defs/DataRef"
+        }
+      ],
+      "description": "The chart data: exactly one of inline values or an external reference."
+    },
+    "DomainValue": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "A domain entry: a number for quantitative, an ISO 8601 string for temporal, or a category value for ordinal/nominal."
+    },
+    "ScaleHint": {
+      "type": "object",
+      "properties": {
+        "domain": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/DomainValue"
+          }
+        },
+        "nice": {
+          "type": "boolean",
+          "description": "Round the domain to human-friendly values."
+        },
+        "zero": {
+          "type": "boolean",
+          "description": "Force the domain to include zero."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Optional scale hints. Interpreters may infer or override these."
+    },
+    "Scales": {
+      "type": "object",
+      "properties": {
+        "x": {
+          "$ref": "#/$defs/ScaleHint"
+        },
+        "y": {
+          "$ref": "#/$defs/ScaleHint"
+        }
+      },
+      "additionalProperties": false,
+      "description": "Per-channel scale hints."
+    },
+    "Config": {
+      "type": "object",
+      "properties": {
+        "title": {
+          "type": "string",
+          "description": "The chart title."
+        },
+        "tooltip": {
+          "type": "boolean",
+          "description": "Whether tooltips are enabled. A trivial declarative hint — real interaction is per-platform application code, not document data."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Portable presentation hints."
+    },
+    "Extensions": {
+      "type": "object",
+      "description": "Web-only, non-portable hints. Native interpreters ignore this entirely."
+    },
+    "TreeOptions": {
+      "type": "object",
+      "properties": {
+        "orientation": {
+          "type": "string",
+          "enum": [
+            "vertical",
+            "horizontal"
+          ],
+          "description": "Vertical: roots at the top. Horizontal: roots at the start edge."
+        },
+        "linkStyle": {
+          "type": "string",
+          "enum": [
+            "orthogonal",
+            "curved"
+          ],
+          "description": "How a parent joins its children."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Spec 1.1: layout options of the \"tree\" mark. Only valid with mark \"tree\"."
+    },
+    "ChartSpec": {
+      "type": "object",
+      "properties": {
+        "specVersion": {
+          "$ref": "#/$defs/SpecVersion"
+        },
+        "mark": {
+          "$ref": "#/$defs/Mark"
+        },
+        "encoding": {
+          "$ref": "#/$defs/Encoding"
+        },
+        "data": {
+          "$ref": "#/$defs/Data"
+        },
+        "scales": {
+          "$ref": "#/$defs/Scales"
+        },
+        "config": {
+          "$ref": "#/$defs/Config"
+        },
+        "extensions": {
+          "$ref": "#/$defs/Extensions"
+        },
+        "tree": {
+          "$ref": "#/$defs/TreeOptions"
+        }
+      },
+      "required": [
+        "specVersion",
+        "mark",
+        "encoding",
+        "data"
+      ],
+      "additionalProperties": false,
+      "title": "Portable Chart Specification",
+      "description": "A renderer-agnostic, framework-agnostic, language-neutral chart description. Grammar-of-graphics level: mark + encodings + declared data types + data reference."
+    }
+  }
+}