global-state expression

build/generate-docs.ts

@@ -1,6 +1,7 @@
 import v8 from '../src/reference/v8.json' with { type: 'json' };
 import fs from 'fs';
 import jsonStringify from 'json-stringify-pretty-compact';
+import { isFunction } from 'util';
 
 /**
  * This script generates markdown documentation from the JSON schema.
@@ -517,6 +518,11 @@
     fs.writeFileSync(`${BASE_PATH}/expressions.md`, content);
 }
 
+function createSchemaContent() {
+    const content = fs.readFileSync('build/schema.md', 'utf-8');
+    fs.writeFileSync(`${BASE_PATH}/schema.md`, content);
+}
+
 /**
  * Creates the main topics markdown files.
  */
@@ -543,4 +549,5 @@
 createLayersContent();
 createSourcesContent();
 createExpressionsContent();
+createSchemaContent();
 createMainTopics();

build/schema.md

@@ -0,0 +1,79 @@
+# Schema
+
+The value for `state` properties. Defines the default state property value, and its type.
+
+The schema definition follows a subset of [JSON Schema](https://json-schema.org/) but is more strict in terms of what properties are required.
+
+## Data types
+
+### enum
+
+
+The `enum` keyword is used to restrict a value to a fixed set of values. It must be an array with at least one element, where each element is unique.
+
+```json
+{  
+    "enum": ["red", "amber", "green"],
+    "default": "red"
+}
+```
+
+### number
+
+The `number` type is used for any numeric type, either integers or floating point numbers.
+
+```json
+{  
+    "type": "number",
+    "minimum": 0, // optional
+    "maximum": 100, // optional
+    "default": 42
+}
+```
+
+You can define range using optional `minimum` and `maximum` keywords. Range is inclusive.
+
+### string
+
+The `string` type is used for strings of text. It may contain Unicode characters.
+
+```json
+{  
+    "type": "string",
+    "default": "Montréal"
+}
+```
+
+### boolean
+
+The `boolean` type matches only two special values: `true` and `false`.
+
+```json
+{  
+    "type": "boolean",
+    "default": true
+}
+```
+
+### array
+
+Arrays are used for ordered elements. Type of items in an array is defined with required `items`. Allowed item types are all schema types. 
+
+```json
+{  
+    "type": "array",
+    "items": {
+        "type": "string"
+    },
+    "default": ["red", "amber", "green"]
+}
+```
+
+## Default values
+
+A default value is required for each data type and is defined with the `default` keyword. The value of the default will be validated against the data type during style validation.
+
+
+## Annotations
+
+The `title` and `description` keywords must be strings. A "title" will preferably be short, whereas a "description" will provide a more lengthy explanation of the purpose of the data described by the schema.

src/reference/v8.json

@@ -100,11 +100,13 @@
     "state": {
       "type": "state",
       "default": {},
-      "doc": "The initial state of the style. This object is a set of key-value pairs. The state key must be a string. The value is a JSON Schema. Supported types are: number, boolean, string, array, enum. Property \"default\" is required. State values can be retrieved with the [`global-state`](https://maplibre.org/maplibre-style-spec/expressions/#global-state) expression.\n\nThis property is required if any layer uses the `global-state` expression.",
+      "doc": "The initial state of the style. This object where keys are property names and value a [`schema`](https://maplibre.org/maplibre-style-spec/schema) definition. State property value can be retrieved with the [`global-state`](https://maplibre.org/maplibre-style-spec/expressions/#global-state) expression.\n\n State is required when `global-state` is used in the style",
       "example": {
         "chargerType": {
           "type": "array",
-          "items": "string",
+          "items": {
+            "type": "string"
+          },
           "default": ["CCS", "CHAdeMO", "Type2"]
         },
         "minPreferredChargingSpeed": {