@lix-js/sdk 0.6.0-preview.0 → 0.6.0-preview.2

package/dist-engine-src/src/schema/definition.json

@@ -0,0 +1,157 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Lix Schema Definition",
+  "description": "A Lix schema is a JSON Schema draft 2020-12 document augmented with `x-lix-*` extensions that identify, version, and constrain an entity type. Every schema must declare `x-lix-key` (snake_case identifier, preferably prefixed with a plugin or domain namespace such as `library_book` to avoid collisions), `x-lix-version` (string-as-integer, e.g. `\"1\"`), and `additionalProperties: false`; add `x-lix-primary-key` (array of JSON Pointers) to make the schema writable — Lix will auto-materialize a public virtual table named after `x-lix-key` with an `INSERT/UPDATE/DELETE` surface. See the `examples` field for a minimal working schema.",
+  "examples": [
+    {
+      "x-lix-key": "library_book",
+      "x-lix-version": "1",
+      "type": "object",
+      "x-lix-primary-key": ["/id"],
+      "properties": {
+        "id": { "type": "string", "x-lix-default": "lix_uuid_v7()" },
+        "title": { "type": "string" },
+        "author": { "type": "string" }
+      },
+      "required": ["id", "title"],
+      "additionalProperties": false
+    }
+  ],
+  "allOf": [
+    {
+      "$ref": "https://json-schema.org/draft/2020-12/schema"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "x-lix-unique": {
+          "type": "array",
+          "description": "Array of composite unique constraints. Each inner array is a JSON Pointer (RFC 6901) per participating property, e.g. `[[\"/email\"], [\"/tenant_id\", \"/handle\"]]`.",
+          "items": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "format": "json-pointer",
+              "description": "JSON Pointer (RFC 6901) to the property, e.g. `/id` or `/nested/field`. Note the leading slash."
+            }
+          }
+        },
+        "additionalProperties": {
+          "type": "boolean",
+          "const": false,
+          "description": "Objects describing Lix schemas must not allow arbitrary additional properties; set this explicitly to false."
+        },
+        "x-lix-primary-key": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "description": "Primary-key fields as JSON Pointers (RFC 6901) into the entity, e.g. `[\"/id\"]` for a single-column key or `[\"/tenant_id\", \"/handle\"]` for a composite key. Note the leading slash; `\"id\"` without a slash is not a valid pointer.",
+          "items": {
+            "type": "string",
+            "format": "json-pointer",
+            "description": "JSON Pointer (RFC 6901) to a property that participates in the primary key, e.g. `/id` or `/nested/field`."
+          }
+        },
+        "x-lix-foreign-keys": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "properties",
+              "references"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "properties": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "format": "json-pointer",
+                  "description": "JSON Pointer (RFC 6901) to the local field, e.g. `/author_id` or `/nested/field`."
+                },
+                "uniqueItems": true,
+                "description": "Local-side participants in the FK, as JSON Pointers (RFC 6901), e.g. `[\"/author_id\"]` or `[\"/tenant_id\", \"/account_id\"]`."
+              },
+              "references": {
+                "type": "object",
+                "required": [
+                  "schemaKey",
+                  "properties"
+                ],
+                "additionalProperties": false,
+                "properties": {
+                  "schemaKey": {
+                    "type": "string",
+                    "description": "The x-lix-key of the referenced schema"
+                  },
+                  "properties": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                      "type": "string",
+                      "format": "json-pointer",
+                      "description": "JSON Pointer (RFC 6901) to the remote field on the referenced schema, e.g. `/id`."
+                    },
+                    "uniqueItems": true,
+                    "description": "Remote-side participants on the referenced schema, as JSON Pointers (RFC 6901). Must be the same length as the local `properties`."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "x-lix-key": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]*$",
+          "description": "The schema identifier. Must be snake_case (lowercase, underscores) to safely embed in SQL identifiers. Prefix keys with a plugin, app, or domain namespace such as `library_book` or `csv_plugin_cell` to avoid collisions with other schemas.",
+          "examples": [
+            "library_book",
+            "csv_plugin_cell"
+          ]
+        },
+        "x-lix-version": {
+          "type": "string",
+          "pattern": "^[1-9]\\d*$",
+          "description": "Schema version identifier. Deliberately constrained to a monotonic integer (as a string) without leading zeros to keep translation rules open while avoiding future breaking changes.",
+          "examples": [
+            "1"
+          ]
+        },
+        "properties": {
+          "type": "object",
+          "additionalProperties": {
+            "allOf": [
+              {
+                "$ref": "https://json-schema.org/draft/2020-12/schema"
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "x-lix-default": {
+                    "type": "string",
+                    "format": "cel",
+                    "description": "CEL expression evaluated to produce the default value when the property is omitted. Available Lix-registered functions: `lix_uuid_v7()` (RFC 9562 UUIDv7), `lix_timestamp()` (ISO-8601 string). CEL literals are also valid: strings (`'open'`), numbers (`0`, `3.14`), booleans (`true` / `false`), and `null`.",
+                    "examples": [
+                      "lix_uuid_v7()",
+                      "lix_timestamp()",
+                      "false",
+                      "'open'"
+                    ]
+                  }
+                }
+              }
+            ]
+          }
+        }
+      },
+      "required": [
+        "x-lix-key",
+        "x-lix-version",
+        "additionalProperties"
+      ]
+    }
+  ]
+}