@vantis/data 0.0.1

package/vantis.schema.schema.json

@@ -0,0 +1,494 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "Access": {
+      "description": "Access-control tier for a table. \"private\" is the current supported value. \"public\" (VAN-844) and \"owned\" (Auth block) are reserved for future tiers.",
+      "enum": [
+        "private"
+      ],
+      "type": "string"
+    },
+    "Column": {
+      "additionalProperties": false,
+      "description": "A single column in a table.",
+      "properties": {
+        "default": {
+          "$ref": "#/definitions/Default",
+          "description": "Optional default value for this column."
+        },
+        "name": {
+          "$ref": "#/definitions/Identifier",
+          "description": "Column name."
+        },
+        "nullable": {
+          "default": false,
+          "description": "Whether the column accepts NULL. Defaults to false (NOT NULL). Incompatible with primary_key:true.",
+          "type": "boolean"
+        },
+        "primary_key": {
+          "default": false,
+          "description": "Whether this column is (part of) the primary key. Primary-key columns are implicitly NOT NULL.",
+          "type": "boolean"
+        },
+        "searchable": {
+          "default": false,
+          "description": "Whether this column participates in full-text search. Requires spec version 2 and a text or varchar column type.",
+          "type": "boolean"
+        },
+        "type": {
+          "$ref": "#/definitions/ColumnTypeName",
+          "description": "Column type."
+        },
+        "unique": {
+          "default": false,
+          "description": "Whether this column has a UNIQUE constraint.",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "name",
+        "type"
+      ],
+      "type": "object"
+    },
+    "ColumnTypeName": {
+      "description": "Closed set of supported Postgres column types.",
+      "enum": [
+        "bigint",
+        "boolean",
+        "date",
+        "double",
+        "integer",
+        "jsonb",
+        "numeric",
+        "real",
+        "text",
+        "timestamptz",
+        "uuid",
+        "varchar"
+      ],
+      "type": "string"
+    },
+    "Default": {
+      "description": "Closed default-value grammar. Raw SQL expressions are intentionally absent — this grammar bounds injection from customer-supplied defaults. Each branch of the discriminated union requires exactly the kind-specific field that the engine enforces.",
+      "oneOf": [
+        {
+          "additionalProperties": false,
+          "description": "Default with kind \"bool\". Requires exactly the \"bool\" field.",
+          "properties": {
+            "bool": {
+              "description": "Boolean value. Required when kind is \"bool\".",
+              "type": "boolean"
+            },
+            "kind": {
+              "const": "bool",
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind",
+            "bool"
+          ],
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "description": "Default with kind \"builtin\". Requires exactly the \"builtin\" field from the allowlist.",
+          "properties": {
+            "builtin": {
+              "description": "Allowed built-in function call. Required when kind is \"builtin\".",
+              "enum": [
+                "gen_random_uuid()",
+                "now()"
+              ],
+              "type": "string"
+            },
+            "kind": {
+              "const": "builtin",
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind",
+            "builtin"
+          ],
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "description": "Default with kind \"null\". No kind-specific field is permitted.",
+          "properties": {
+            "kind": {
+              "const": "null",
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "description": "Default with kind \"number\". Requires exactly the \"number\" field (stored as a string to avoid float-precision issues).",
+          "properties": {
+            "kind": {
+              "const": "number",
+              "type": "string"
+            },
+            "number": {
+              "description": "Numeric literal. Required when kind is \"number\". Stored as a string to avoid float-precision issues. Only digits, optional leading minus, optional decimal point.",
+              "pattern": "^-?[0-9]+(\\.[0-9]+)?$",
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind",
+            "number"
+          ],
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "description": "Default with kind \"string\". Requires exactly the \"string\" field.",
+          "properties": {
+            "kind": {
+              "const": "string",
+              "type": "string"
+            },
+            "string": {
+              "description": "String literal. Required when kind is \"string\". Must not contain backslash, null byte, carriage return, or newline.",
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind",
+            "string"
+          ],
+          "type": "object"
+        }
+      ]
+    },
+    "DefaultKind": {
+      "description": "Discriminant for the Default object. Exactly one kind-specific field must match the kind value.",
+      "enum": [
+        "bool",
+        "builtin",
+        "null",
+        "number",
+        "string"
+      ],
+      "type": "string"
+    },
+    "ForeignKey": {
+      "additionalProperties": false,
+      "description": "A foreign-key constraint from this table to a referenced table in the same spec.",
+      "properties": {
+        "columns": {
+          "description": "Column(s) in this table that form the foreign key. Must not be empty.",
+          "items": {
+            "$ref": "#/definitions/Identifier"
+          },
+          "minItems": 1,
+          "type": "array"
+        },
+        "name": {
+          "$ref": "#/definitions/Identifier",
+          "description": "Foreign-key constraint name."
+        },
+        "ref_columns": {
+          "description": "Column(s) in the referenced table. Must have the same length as columns.",
+          "items": {
+            "$ref": "#/definitions/Identifier"
+          },
+          "minItems": 1,
+          "type": "array"
+        },
+        "ref_table": {
+          "$ref": "#/definitions/Identifier",
+          "description": "Name of the referenced table (must exist in this spec)."
+        }
+      },
+      "required": [
+        "columns",
+        "name",
+        "ref_columns",
+        "ref_table"
+      ],
+      "type": "object"
+    },
+    "Function": {
+      "additionalProperties": false,
+      "description": "A customer-authored typed RPC over a Postgres function. Requires spec version 3. The engine always emits SECURITY INVOKER; no Security field is accepted.",
+      "properties": {
+        "args": {
+          "description": "Function arguments (may be empty).",
+          "items": {
+            "$ref": "#/definitions/FunctionArg"
+          },
+          "type": "array"
+        },
+        "body": {
+          "description": "PL/pgSQL function body. Raw SQL — not grammar-checked by the schema engine. Must not be empty or exceed 8192 bytes.",
+          "minLength": 1,
+          "type": "string"
+        },
+        "name": {
+          "$ref": "#/definitions/Identifier",
+          "description": "Function name. Reserved prefixes search_ and __vantis_ are rejected; JS meta-keys (then, catch, etc.) are rejected."
+        },
+        "returns": {
+          "$ref": "#/definitions/FunctionReturns",
+          "description": "Return shape."
+        },
+        "timeout_ms": {
+          "description": "Statement timeout in milliseconds. 0 means no per-statement override. Range: 0 to 60000.",
+          "maximum": 60000,
+          "minimum": 0,
+          "type": "integer"
+        },
+        "volatility": {
+          "$ref": "#/definitions/Volatility",
+          "description": "Function volatility category."
+        }
+      },
+      "required": [
+        "body",
+        "name",
+        "returns",
+        "volatility"
+      ],
+      "type": "object"
+    },
+    "FunctionArg": {
+      "additionalProperties": false,
+      "description": "A typed function argument.",
+      "properties": {
+        "name": {
+          "$ref": "#/definitions/Identifier",
+          "description": "Argument name."
+        },
+        "type": {
+          "$ref": "#/definitions/ColumnTypeName",
+          "description": "Argument type."
+        }
+      },
+      "required": [
+        "name",
+        "type"
+      ],
+      "type": "object"
+    },
+    "FunctionReturnCol": {
+      "additionalProperties": false,
+      "description": "A column in a \"returns table\" function result.",
+      "properties": {
+        "name": {
+          "$ref": "#/definitions/Identifier",
+          "description": "Return column name."
+        },
+        "type": {
+          "$ref": "#/definitions/ColumnTypeName",
+          "description": "Return column type."
+        }
+      },
+      "required": [
+        "name",
+        "type"
+      ],
+      "type": "object"
+    },
+    "FunctionReturnKind": {
+      "description": "Return shape: \"scalar\" (a single typed value), \"void\" (no return value), or \"table\" (a set of typed rows).",
+      "enum": [
+        "scalar",
+        "table",
+        "void"
+      ],
+      "type": "string"
+    },
+    "FunctionReturns": {
+      "description": "The return shape of a typed RPC function. Each branch of the discriminated union requires exactly the kind-specific field(s) that the engine enforces.",
+      "oneOf": [
+        {
+          "additionalProperties": false,
+          "description": "Function returns a single scalar value. Requires the \"scalar\" field; \"columns\" is forbidden.",
+          "properties": {
+            "kind": {
+              "const": "scalar",
+              "type": "string"
+            },
+            "scalar": {
+              "$ref": "#/definitions/ColumnTypeName"
+            }
+          },
+          "required": [
+            "kind",
+            "scalar"
+          ],
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "description": "Function returns a set of typed rows. Requires a non-empty \"columns\" list; \"scalar\" is forbidden.",
+          "properties": {
+            "columns": {
+              "description": "Return columns. Required when kind is \"table\". Must not be empty.",
+              "items": {
+                "$ref": "#/definitions/FunctionReturnCol"
+              },
+              "minItems": 1,
+              "type": "array"
+            },
+            "kind": {
+              "const": "table",
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind",
+            "columns"
+          ],
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "description": "Function returns nothing. No \"scalar\" or \"columns\" fields are permitted.",
+          "properties": {
+            "kind": {
+              "const": "void",
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "type": "object"
+        }
+      ]
+    },
+    "Identifier": {
+      "description": "A valid Postgres identifier: lowercase letters, digits, and underscores; must start with a letter or underscore; at most 63 bytes (Postgres NAMEDATALEN-1).",
+      "maxLength": 63,
+      "pattern": "^[a-z_][a-z0-9_]*$",
+      "type": "string"
+    },
+    "Index": {
+      "additionalProperties": false,
+      "description": "An additional index on a table. Index names must be unique across the entire schema (PostgreSQL shares one relation namespace per schema).",
+      "properties": {
+        "columns": {
+          "description": "Ordered column names included in the index. Must not be empty.",
+          "items": {
+            "$ref": "#/definitions/Identifier"
+          },
+          "minItems": 1,
+          "type": "array"
+        },
+        "name": {
+          "$ref": "#/definitions/Identifier",
+          "description": "Index name. Must be unique across all indexes and table names in the schema."
+        },
+        "unique": {
+          "default": false,
+          "description": "Whether this is a UNIQUE index.",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "columns",
+        "name"
+      ],
+      "type": "object"
+    },
+    "Table": {
+      "additionalProperties": false,
+      "description": "A single table in the schema. Table names must be unique; reserved prefixes search_ and __vantis_ are rejected.",
+      "properties": {
+        "access": {
+          "$ref": "#/definitions/Access",
+          "description": "Access-control tier. Defaults to \"private\" when omitted."
+        },
+        "columns": {
+          "description": "Columns in this table. At least one column is required.",
+          "items": {
+            "$ref": "#/definitions/Column"
+          },
+          "minItems": 1,
+          "type": "array"
+        },
+        "foreign_keys": {
+          "description": "Optional foreign-key constraints on this table.",
+          "items": {
+            "$ref": "#/definitions/ForeignKey"
+          },
+          "type": "array"
+        },
+        "indexes": {
+          "description": "Optional additional indexes on this table.",
+          "items": {
+            "$ref": "#/definitions/Index"
+          },
+          "type": "array"
+        },
+        "name": {
+          "$ref": "#/definitions/Identifier",
+          "description": "Table name."
+        }
+      },
+      "required": [
+        "columns",
+        "name"
+      ],
+      "type": "object"
+    },
+    "Volatility": {
+      "description": "PostgreSQL function volatility category.",
+      "enum": [
+        "immutable",
+        "stable",
+        "volatile"
+      ],
+      "type": "string"
+    }
+  },
+  "description": "Vantis declarative schema document (vantis.schema.json). Governs table definitions, column types, indexes, foreign keys, and typed RPC functions. Consumed by `vantis data build`, `plan`, and `apply` (VAN-869, ADR-0048).",
+  "properties": {
+    "$schema": {
+      "const": "https://vantis.build/schema/vantis.schema.json",
+      "description": "Optional editor-tooling hint. If present, must be the canonical Vantis schema URL (ExpectedSchemaURL). Accepted and stripped before downstream use by all Vantis consumers (vantis data build / plan / apply / dev-MCP / schema-runner); any other value is rejected with a clear error. Prefer the VS Code json.schemas workspace setting — the VS Code docs note that in-file $schema is VS Code-specific and not part of the JSON Schema specification (VAN-869 item 2, ADR-0048).",
+      "type": "string"
+    },
+    "functions": {
+      "description": "Customer-authored typed RPC functions over Postgres. Requires spec version 3.",
+      "items": {
+        "$ref": "#/definitions/Function"
+      },
+      "type": "array"
+    },
+    "tables": {
+      "description": "Tables in this schema. At least one table is required.",
+      "items": {
+        "$ref": "#/definitions/Table"
+      },
+      "minItems": 1,
+      "type": "array"
+    },
+    "version": {
+      "description": "Spec version. 1: base tables. 2: adds the searchable annotation for full-text search. 3: adds typed RPC functions.",
+      "enum": [
+        1,
+        2,
+        3
+      ],
+      "type": "integer"
+    }
+  },
+  "required": [
+    "tables",
+    "version"
+  ],
+  "title": "vantis.schema.json",
+  "type": "object"
+}