{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/antfly/json-schema/antfly-table-schema-schema.json",
  "title": "TableSchema",
  "description": "Schema definition for a table with multiple document types",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/antfly-table-management-api-openapi.yml#/components/schemas/TableSchema",
  "type": "object",
  "properties": {
    "version": {
      "type": "integer",
      "format": "uint32",
      "readOnly": true,
      "description": "Backend-managed schema generation used for migrations. Omit it from create and update requests."
    },
    "storage_mode": {
      "$ref": "#/$defs/TableStorageMode"
    },
    "base_source": {
      "$ref": "#/$defs/ExternalLakeTableSource",
      "description": "External tables require relational storage mode. Ordinary row writes are read-only; an explicit iceberg_writer catalog binding permits Iceberg file commits. Omit for native tables."
    },
    "column_defaults": {
      "type": "array",
      "maxItems": 256,
      "items": {
        "$ref": "#/$defs/RelationalColumnExpression"
      },
      "description": "Immutable typed expressions applied only to absent columns on new\nwrites, never explicit null. Defaults cannot reference columns.\nA column cannot have both a default and a generated expression.\nOmission or [] declares none. Relational tables only.\n"
    },
    "generated_columns": {
      "type": "array",
      "maxItems": 256,
      "items": {
        "$ref": "#/$defs/RelationalColumnExpression"
      },
      "description": "Stored immutable generated columns, evaluated in dependency order\non writes before validation and indexing. Cycles are rejected.\nGenerated columns are output-only; submitted values are replaced\nby the computed value. Omission or [] declares none. Defaults\nand generated declarations together are limited to 256 columns,\n4096 expression nodes, and 4 MiB of literal data. Evaluation has\na shared 4 MiB allocation budget across all column expressions.\nRestore verifies stored results instead of silently recomputing\nthem. Changing, adding, or removing generated semantics through\nan existing table's schema update requires explicit rewrite=true\non the PUT or PATCH schema route. This returns a durable restore\njob and replaces the complete authorized dependency cohort only\nafter distributed transformation and validation. Ordinary schema\nupdates reject these changes, even when a table appears empty.\nDeclaration reordering and default-only changes remain allowed.\nRelational tables only.\n"
    },
    "checks": {
      "type": "array",
      "maxItems": 256,
      "items": {
        "$ref": "#/$defs/RelationalCheckConstraint"
      },
      "description": "Named scalar CHECK constraints for a relational schema. This is\npart of the complete schema: omission or [] declares no checks.\nNew writes enforce every check. Existing-row validation status is\nmaintained separately and is never accepted from the client.\n"
    },
    "unique_constraints": {
      "type": "array",
      "maxItems": 256,
      "items": {
        "$ref": "#/$defs/RelationalUniqueConstraint"
      },
      "description": "Complete set of composite unique declarations. Omission or [] declares none."
    },
    "foreign_keys": {
      "type": "array",
      "maxItems": 256,
      "items": {
        "$ref": "#/$defs/RelationalForeignKeyConstraint"
      },
      "description": "Complete set of outgoing composite foreign keys. Omission or [] declares none."
    },
    "relational_indexes": {
      "type": "array",
      "x-go-type-skip-optional-pointer": false,
      "maxItems": 4096,
      "items": {
        "$ref": "#/$defs/RelationalIndexDefinition"
      },
      "description": "Desired ordered indexes for a relational table. Names must be unique.\nAn explicit array replaces the declarations; an empty array drops\nthem. Omission preserves existing declarations during schema updates.\nIndex definitions commit atomically with the schema; build progress\nand readiness are local to each owning shard, not client-writable.\n"
    },
    "default_type": {
      "type": "string",
      "description": "Default type to use from the document_schemas."
    },
    "enforce_types": {
      "type": "boolean",
      "description": "Whether to enforce that documents must match one of the provided document types.\nIf false, documents not matching any type will be accepted but not indexed.\n"
    },
    "document_schemas": {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/$defs/DocumentSchema"
      },
      "description": "A map of type names to their document json schemas."
    },
    "ttl": {
      "allOf": [
        {
          "$ref": "#/$defs/TtlConfig"
        }
      ],
      "description": "Automatic document expiration. Set this object to enable TTL and\nset it to null to disable an existing TTL policy.\n"
    },
    "ttl_field": {
      "type": "string",
      "deprecated": true,
      "description": "Deprecated compatibility alias for `ttl.field`. Cannot be combined with `ttl`.\n"
    },
    "ttl_duration": {
      "type": "string",
      "deprecated": true,
      "description": "Deprecated compatibility alias for `ttl.duration`. Cannot be combined with `ttl`.\n"
    },
    "dynamic_templates": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/DynamicTemplate"
      },
      "description": "Rules for mapping dynamically detected fields. When a document contains fields\nthat don't have explicit mappings and dynamic mapping is enabled, templates are\nevaluated in order to determine how those fields should be indexed.\n"
    }
  },
  "$defs": {
    "DocumentFieldMapping": {
      "type": "object",
      "additionalProperties": false,
      "description": "Executable physical mapping used by a document property's `x-antfly-field` annotation. The mapping must accept the JSON Schema value type. Declarations for the same dotted path across document types must normalize to an identical physical mapping, and present values that cannot be encoded are rejected at write admission. Mappings contributed by `anyOf` or `oneOf` must normalize to the same mapping in every alternative; conditional and dynamically named mappings are rejected.",
      "properties": {
        "type": {
          "$ref": "#/$defs/FieldMappingType"
        },
        "analyzer": {
          "type": "string",
          "description": "Analyzer name for text-oriented mappings."
        },
        "index": {
          "type": "boolean",
          "x-go-type-skip-optional-pointer": false,
          "description": "Whether to index the field. Omit to use the server default of true."
        },
        "store": {
          "type": "boolean",
          "default": false,
          "description": "Whether to store the field value (default false)"
        },
        "include_in_all": {
          "type": "boolean",
          "default": false,
          "description": "Whether to include in the _all field for cross-field search"
        },
        "sortable": {
          "type": "boolean",
          "default": false,
          "description": "Whether this exact scalar field can be used in order_by. Supported\nsortable mapping types are keyword, numeric/number/integer,\nboolean/bool, datetime/date/timestamp, and link. Analyzed text,\nsearch_as_you_type, geo, embedding, blob, html, object, and array\nfields are not directly sortable; use an exact scalar subfield such\nas title.keyword for sorted string pagination. Antfly derives the\nrequired typed doc values when enabled.\n"
        },
        "missing_null_policy": {
          "type": "string",
          "enum": [
            "missing_rejected",
            "nulls_ordered"
          ],
          "default": "missing_rejected",
          "description": "Missing/null sort policy. The default missing_rejected rejects missing or null native sort values. Opt in to nulls_ordered for nulls first ascending and last descending, with JSON null cursor components. Nullable native layouts require a complete producer proof."
        },
        "fields": {
          "type": "object",
          "description": "Named one-level multifields emitted from this property's value. For example, a text title can expose a sortable keyword subfield.",
          "additionalProperties": {
            "$ref": "#/$defs/DocumentSubfieldMapping"
          }
        }
      }
    },
    "DocumentSchema": {
      "type": "object",
      "description": "Defines the structure of a document type",
      "properties": {
        "description": {
          "type": "string",
          "description": "A description of the document type."
        },
        "schema": {
          "type": "object",
          "additionalProperties": true,
          "description": "A valid JSON Schema defining the document's structure.\nThis is used to infer indexing rules and field types.\n",
          "x-antfly-field-mapping-schema": {
            "$ref": "#/$defs/DocumentFieldMapping"
          },
          "x-antfly-sql-type-schema": {
            "$ref": "#/$defs/SQLBuiltinType"
          },
          "x-antfly-sql-numeric-modifier-schema": {
            "$ref": "#/$defs/SQLNumericModifier"
          },
          "x-antfly-sql-array-column-schema": {
            "$ref": "#/$defs/SQLArrayColumnSchema"
          }
        }
      }
    },
    "DocumentSubfieldMapping": {
      "type": "object",
      "additionalProperties": false,
      "description": "Mapping for one named multifield emitted from its parent document property. Multifields are intentionally one level deep and read the parent property's JSON value rather than a nested JSON property.",
      "properties": {
        "type": {
          "$ref": "#/$defs/FieldMappingType"
        },
        "analyzer": {
          "type": "string",
          "description": "Analyzer name for text-oriented mappings."
        },
        "index": {
          "type": "boolean",
          "x-go-type-skip-optional-pointer": false,
          "description": "Whether to index the field. Omit to use the server default of true."
        },
        "store": {
          "type": "boolean",
          "default": false,
          "description": "Whether to store the field value (default false)"
        },
        "include_in_all": {
          "type": "boolean",
          "default": false,
          "description": "Whether to include in the _all field for cross-field search"
        },
        "sortable": {
          "type": "boolean",
          "default": false,
          "description": "Whether this exact scalar subfield can be used in order_by. Antfly derives the required typed doc values when enabled."
        },
        "missing_null_policy": {
          "type": "string",
          "enum": [
            "missing_rejected",
            "nulls_ordered"
          ],
          "default": "missing_rejected",
          "description": "Missing/null sort policy. The default missing_rejected rejects missing or null native sort values. Opt in to nulls_ordered for nulls first ascending and last descending, with JSON null cursor components. Nullable native layouts require a complete producer proof."
        }
      }
    },
    "DynamicTemplate": {
      "type": "object",
      "additionalProperties": false,
      "description": "A rule for mapping dynamically detected fields. Templates are checked in order\nand the first matching template's mapping is used.\n",
      "properties": {
        "name": {
          "type": "string",
          "description": "Optional identifier for the template (useful for debugging)"
        },
        "match": {
          "type": "string",
          "description": "Glob pattern for field name (last path element).\nSupports * and ** wildcards. Example: \"*_text\" matches \"title_text\", \"body_text\"\n"
        },
        "unmatch": {
          "type": "string",
          "description": "Exclusion pattern for field name. If it matches, the template is skipped.\nExample: \"skip_*\" would exclude fields like \"skip_this\"\n"
        },
        "path_match": {
          "type": "string",
          "description": "Glob pattern for the full dotted path. Supports ** for matching multiple segments.\nExample: \"metadata.**\" matches \"metadata.author\", \"metadata.tags.primary\"\n"
        },
        "path_unmatch": {
          "type": "string",
          "description": "Path exclusion pattern. If it matches the full path, the template is skipped."
        },
        "match_mapping_type": {
          "type": "string",
          "enum": [
            "string",
            "number",
            "boolean",
            "date",
            "object"
          ],
          "description": "Filter by detected JSON type"
        },
        "mapping": {
          "$ref": "#/$defs/TemplateFieldMapping"
        }
      }
    },
    "ExternalLakeCredentialRef": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "ref"
      ],
      "properties": {
        "ref": {
          "type": "string",
          "minLength": 1,
          "description": "Name of a configured external_io connection with lake.read capability."
        },
        "scope": {
          "type": "string",
          "description": "Allowed object prefix relative to the configured bucket or filesystem root."
        }
      }
    },
    "ExternalLakeSnapshotSelector": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "mode"
      ],
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "current",
            "snapshot_id",
            "object_version_digest"
          ]
        },
        "id": {
          "type": "string",
          "minLength": 1,
          "description": "Required for snapshot_id; selects an Iceberg snapshot."
        },
        "digest": {
          "type": "string",
          "minLength": 1,
          "description": "Required for object_version_digest; pins a Parquet object inventory."
        }
      }
    },
    "ExternalLakeTableSource": {
      "type": "object",
      "additionalProperties": false,
      "description": "Authoritative Parquet or Iceberg source. A serving statement pins its inventory and object versions before returning rows. Iceberg catalog commits require an explicit writable catalog binding; ordinary row mutations remain unsupported.",
      "required": [
        "kind",
        "table_id",
        "format",
        "uri"
      ],
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "external"
          ]
        },
        "table_id": {
          "type": "string",
          "minLength": 1
        },
        "format": {
          "type": "string",
          "enum": [
            "parquet",
            "iceberg"
          ]
        },
        "uri": {
          "type": "string",
          "minLength": 1,
          "description": "Parquet prefix, Iceberg table, or an explicit Parquet snapshot head ending in .parquet-manifest.json. Snapshot heads name immutable checksummed file-list chunks; each query revalidates the head without listing the data prefix."
        },
        "row_identity_version": {
          "type": "integer",
          "enum": [
            1,
            2
          ],
          "readOnly": true,
          "description": "Server-assigned public row identity version, fixed when the source is attached and preserved across index creation and schema updates."
        },
        "row_identity": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "key_columns"
          ],
          "description": "Optional verified stable identity for external rewrites. Keys must be non-null and unique in each published snapshot. Uses native typed equality; an unchanged key alone never authorizes index reuse.",
          "properties": {
            "key_columns": {
              "type": "array",
              "minItems": 1,
              "maxItems": 32,
              "items": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        },
        "schema_fingerprint": {
          "type": "string",
          "default": "auto",
          "minLength": 1
        },
        "write_policy": {
          "type": "string",
          "enum": [
            "read_only",
            "iceberg_writer"
          ],
          "default": "read_only",
          "description": "iceberg_writer authorizes explicit Iceberg catalog commits and requires catalog plus a current snapshot selector. It does not enable ordinary row batch writes."
        },
        "object_mutability": {
          "type": "string",
          "enum": [
            "mutable",
            "immutable"
          ],
          "default": "mutable",
          "description": "Set immutable only when data files are never replaced at an existing URI. Allows authenticated provider-version proofs from retained index generations to be reused for unchanged data files. Metadata and delete files are still verified."
        },
        "credentials": {
          "$ref": "#/$defs/ExternalLakeCredentialRef"
        },
        "snapshot": {
          "$ref": "#/$defs/ExternalLakeSnapshotSelector"
        },
        "catalog": {
          "$ref": "#/$defs/LakeCatalogConfig"
        }
      }
    },
    "FieldMappingType": {
      "type": "string",
      "description": "Field types accepted by detailed `x-antfly-field` and dynamic-template\nmappings. JSON-schema-oriented aliases are normalized to Antfly's\ncorresponding runtime type: number/integer to numeric, bool to boolean,\ndate/timestamp to datetime, geo_point to geopoint, and geo_shape to\ngeoshape.\n",
      "enum": [
        "text",
        "html",
        "keyword",
        "numeric",
        "number",
        "integer",
        "boolean",
        "bool",
        "datetime",
        "date",
        "timestamp",
        "geopoint",
        "geo_point",
        "geoshape",
        "geo_shape",
        "embedding",
        "blob",
        "link",
        "search_as_you_type",
        "substring"
      ]
    },
    "ForeignKeyAction": {
      "type": "string",
      "enum": [
        "restrict",
        "set_null",
        "cascade",
        "no_action"
      ],
      "description": "Action on referencing rows when a referenced row is changed or removed."
    },
    "ForeignKeyMatch": {
      "type": "string",
      "enum": [
        "simple",
        "full",
        "partial"
      ],
      "description": "Null matching semantics of a composite foreign key. Partial requires\nat least one parent matching every non-null child component; all-null\nchildren are exempt. Compatible parent witnesses are guarded through\ncommit, including concurrent deletion of alternative witnesses.\n"
    },
    "ForeignKeyTiming": {
      "type": "string",
      "enum": [
        "immediate",
        "deferred"
      ],
      "description": "Enforcement timing for atomic mutations and transaction sessions. Deferred\nrequires deferrable=true and validates the final transaction state.\nNO ACTION permits a valid final-state parent replacement; RESTRICT\nstill rejects referenced parent removal. Existing multi-request\ntransaction sessions retain deferred checks until commit; immediate\nchecks apply to each staged statement. SET CONSTRAINTS is not provided.\n"
    },
    "LakeCatalogConfig": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "description": "Catalog authority is independent of S3/GCS storage and deployment. managed uses a conditional durable head under the table root. rest uses a named HTTP connection; raw secrets are forbidden. Omit to retain explicit metadata URI/version-hint discovery.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "managed",
            "rest"
          ]
        },
        "connection": {
          "type": "string",
          "description": "Required for rest. Named external_io/http connection with lake_catalog_read and, for commits, lake_catalog_write capabilities."
        },
        "uri": {
          "type": "string",
          "description": "Required for rest; catalog base URI whose origin must be allowed by the named connection."
        },
        "namespace": {
          "type": "array",
          "maxItems": 32,
          "items": {
            "type": "string"
          },
          "description": "Required nonempty namespace components for rest."
        },
        "name": {
          "type": "string",
          "description": "Required table name for rest, distinct from Antfly's logical table name."
        },
        "warehouse": {
          "type": "string",
          "description": "Optional REST config warehouse selector. Other fields must be omitted for managed."
        }
      }
    },
    "RelationalCheckConstraint": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name"
      ],
      "description": "A typed CHECK. Supply either expression or column and op (with optional\nvalue and collation), never both forms. Expressions must return boolean\nand use the shared bounded immutable scalar expression vocabulary.\nNew writes are checked from schema publication;\nexisting rows are validated separately. SQL UNKNOWN satisfies CHECK.\nComparison values must match the column type. Integer values may also\nuse exact decimal strings to avoid client-side floating-point rounding.\n",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256
        },
        "column": {
          "type": "string",
          "minLength": 1
        },
        "op": {
          "$ref": "#/$defs/RelationalComparisonOp"
        },
        "value": {
          "description": "Scalar comparison operand. Omission represents NULL. Null tests require a NULL operand."
        },
        "collation": {
          "type": "string",
          "description": "String comparison collation; uses the same rules as ordered indexes."
        },
        "expression": {
          "$ref": "#/$defs/RelationalScalarExpression"
        }
      }
    },
    "RelationalColumnExpression": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "column",
        "expression"
      ],
      "properties": {
        "column": {
          "type": "string",
          "minLength": 1
        },
        "expression": {
          "$ref": "#/$defs/RelationalScalarExpression"
        }
      }
    },
    "RelationalComparisonOp": {
      "type": "string",
      "enum": [
        "is_null",
        "is_not_null",
        "eq",
        "ne",
        "gt",
        "gte",
        "lt",
        "lte",
        "is_distinct",
        "is_not_distinct"
      ]
    },
    "RelationalExpressionOp": {
      "type": "string",
      "enum": [
        "literal",
        "column",
        "add",
        "subtract",
        "multiply",
        "divide",
        "negate",
        "concat",
        "coalesce",
        "lower_ascii",
        "upper_ascii",
        "eq",
        "ne",
        "gt",
        "gte",
        "lt",
        "lte",
        "is_null",
        "is_not_null",
        "is_distinct",
        "is_not_distinct",
        "and",
        "or",
        "not",
        "cast",
        "case_when",
        "modulo",
        "in_list",
        "not_in_list",
        "array"
      ]
    },
    "RelationalExpressionType": {
      "type": "string",
      "enum": [
        "string",
        "blob",
        "boolean",
        "datetime",
        "integer",
        "number",
        "numeric",
        "sql_array"
      ]
    },
    "RelationalForeignKeyConstraint": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "child_columns",
        "parent_table",
        "parent_columns"
      ],
      "description": "Composite foreign key. Child and parent columns correspond by position\nand must have the same physical comparison types. The parent columns\nmust identify a unique key. Existing-row validation is independent of\nnew-write enforcement and is never client-writable.\nEnforcement and referential actions share the bounded distributed\ntransaction path, including TTL expiry. Partial matching uses ordered\nsupport indexes on the parent; activation waits until these are ready.\nSET NULL requires every child column to accept explicit NULL.\n",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256
        },
        "child_columns": {
          "type": "array",
          "minItems": 1,
          "maxItems": 32,
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "parent_table": {
          "type": "string",
          "minLength": 1,
          "description": "Literal parent table name in the child table's database and namespace.\nResolved to an immutable table identity when the constraint is declared;\nrenaming a parent preserves the reference. Public schemas show its current name.\n"
        },
        "parent_columns": {
          "type": "array",
          "minItems": 1,
          "maxItems": 32,
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "on_delete": {
          "$ref": "#/$defs/ForeignKeyAction"
        },
        "on_update": {
          "$ref": "#/$defs/ForeignKeyAction"
        },
        "timing": {
          "$ref": "#/$defs/ForeignKeyTiming"
        },
        "match": {
          "$ref": "#/$defs/ForeignKeyMatch"
        },
        "deferrable": {
          "type": "boolean"
        }
      }
    },
    "RelationalIndexDefinition": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "keys"
      ],
      "description": "Declarative table-owned ordered index. Keys are compared lexicographically\nin the declared order, with independent direction, null placement, and\nstring collation. Creation builds existing rows asynchronously; queries\nmust wait for range-local coverage. Unique constraints and expression\nkeys are not implied by this object. Optional WHERE conjuncts select\nonly matching rows. INCLUDE columns\nstore typed values alongside keys for index-only projected reads.\n",
      "properties": {
        "description": {
          "type": "string",
          "description": "Optional human-readable description, also exposed by the shared indexes API."
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256
        },
        "keys": {
          "type": "array",
          "minItems": 1,
          "maxItems": 32,
          "items": {
            "$ref": "#/$defs/RelationalIndexKey"
          }
        },
        "include_columns": {
          "type": "array",
          "maxItems": 256,
          "uniqueItems": true,
          "description": "Non-key columns stored in the index; must be distinct from key columns.",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "where": {
          "type": "array",
          "maxItems": 256,
          "description": "Conjunction of typed predicates. Indexed queries must explicitly contain every conjunct with equivalent typed comparison semantics.",
          "items": {
            "$ref": "#/$defs/RelationalIndexPredicate"
          }
        }
      }
    },
    "RelationalIndexKey": {
      "type": "object",
      "additionalProperties": false,
      "description": "Ordered component of a relational ordered-tuple index key. Supply\neither a declared column or a deterministic typed scalar expression\nwith its result_type. Composite keys may mix both forms. Bounds use\nthe expression result type, not its input columns.\n",
      "properties": {
        "column": {
          "type": "string",
          "minLength": 1,
          "description": "Declared relational column used by this key component."
        },
        "expression": {
          "$ref": "#/$defs/RelationalScalarExpression"
        },
        "result_type": {
          "$ref": "#/$defs/RelationalExpressionType"
        },
        "collation": {
          "type": "string",
          "minLength": 1,
          "description": "String-key collation. Omission selects binary ordering. Supported\nbinary aliases are C, POSIX, and binary. The aliases ci,\ncase_insensitive, and antfly.case_insensitive select ASCII-only\ncase folding, not locale-aware or Unicode case folding.\n"
        },
        "direction": {
          "$ref": "#/$defs/RelationalIndexKeyDirection"
        },
        "nulls": {
          "$ref": "#/$defs/RelationalIndexKeyNulls"
        }
      }
    },
    "RelationalIndexKeyDirection": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "description": "Direction of one ordered index key component. Omission selects asc."
    },
    "RelationalIndexKeyNulls": {
      "type": "string",
      "enum": [
        "default",
        "first",
        "last"
      ],
      "description": "Null placement for one ordered index key component. The default is\nlast for ascending keys and first for descending keys. Omission selects default.\n"
    },
    "RelationalIndexPredicate": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "column",
        "op"
      ],
      "description": "A typed partial-index conjunct. Only TRUE is indexed; FALSE and SQL UNKNOWN are excluded.",
      "properties": {
        "column": {
          "type": "string",
          "minLength": 1
        },
        "op": {
          "$ref": "#/$defs/RelationalComparisonOp"
        },
        "value": {
          "description": "Typed scalar operand; integer columns also accept exact decimal strings. Omission means NULL."
        },
        "collation": {
          "type": "string",
          "description": "String comparison collation with the same semantics as ordered keys."
        }
      }
    },
    "RelationalScalarExpression": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "op"
      ],
      "description": "Immutable typed scalar expression, limited to 128 nodes and 16 levels.\nA literal requires type; omitted value means typed null. A column\nrequires column; other\noperations require args. Unknown or irrelevant fields are rejected.\nArithmetic operands have the same integer or number type. Integer\ndivision truncates toward zero. Overflow and division by zero reject\nthe write. Arithmetic and string operations propagate null. ASCII case\noperations leave non-ASCII bytes unchanged. No volatile functions are\naccepted. Allocated results are bounded to 1 MiB each. Allocations\nand byte-comparison operand work share a 4 MiB evaluation budget per\nrow and expression set. An integer literal may use a decimal string\nfor exact int64 transport; blob uses base64 and datetime uses the\nnormal relational datetime representation.\nComparisons require operands of compatible types (integer and number may mix) and return boolean or\nSQL UNKNOWN (null); is_distinct and is_not_distinct always return a\nboolean. Unary is_null and is_not_null test presence/null. AND and OR\nevaluate left to right with SQL three-valued short-circuit semantics;\nNOT preserves UNKNOWN. CHECK accepts TRUE and UNKNOWN, rejecting FALSE.\nNumeric literals and arithmetic operations may specify sql_type to\nretain PostgreSQL builtin overflow and float4 rounding semantics.\nWithout it, integer and number operations retain int64 and float64\nsemantics. Numeric cast requires type and sql_type, takes one numeric\nargument, and performs a checked conversion when evaluated (not when\nthe schema is compiled). Floating-to-integer casts round ties to even.\nThe numeric expression type uses exact PostgreSQL NUMERIC values and\nmay specify sql_type numeric. Its literals accept decimal strings or\nexact JSON numeric lexemes, including string-valued special values.\nExact NUMERIC programs require reader capability version 21 even when\ntheir result is boolean or integer. Float/integer assignment casts keep\ntheir declared PostgreSQL rounding and overflow semantics.\nA cast to numeric may specify numeric_modifier for PostgreSQL precision\nand signed-scale coercion. Overflow is checked when the selected cast\nexecutes; unselected lazy branches do not fail. Modifier-bearing programs\nrequire reader capability version 23 even with integer/boolean output.\nThe sql_array expression type requires sql_type on literals, including\ntyped NULL, to declare the element builtin. Non-null literals use the\nordinal SQL array envelope (dimensions with length/lower_bound, values,\nand sql_nulls), retaining shape and lower bounds. Array columns derive\ntheir exact element identity from the immutable schema. Comparisons,\nIN, COALESCE and CASE require matching array element identities; no\nelement type is inferred from values. Array-dependent programs require\nreader capability version 24 even with scalar output. Assignment to a\nNUMERIC array column applies its precision/signed-scale modifier to\neach element. Array casts require type sql_array and an explicit matching\nsql_type; identity casts borrow the immutable input. Casts of numeric\narrays may additionally specify numeric_modifier, coercing each non-NULL\nelement with PostgreSQL precision and signed-scale semantics while\npreserving dimensions, lower bounds and NULL slots. Coercion is lazy\nand shares invocation admission with the surrounding expression.\nArray-valued ordered index keys and element-changing array casts are\nnot supported by this expression contract.\nThe array constructor requires sql_type and zero to 32 arguments.\nConstructor programs additionally require reader capability version 25,\nincluding constructors hidden inside scalar/boolean expressions.\nScalar arguments must have the declared element domain, with explicit\nwidth-preserving numeric casts where needed. SQL NULL arguments become\nNULL elements. Array arguments must all have matching element types,\ndimensions and lower bounds; one leading dimension with lower bound 1\nis added. All empty/NULL subarrays produce an empty array; mixing an\nempty/NULL subarray with a nonempty one is a dimension mismatch. Child\nexpressions execute once, with shared work/cancellation and byte limits.\ncase_when takes alternating boolean conditions and result expressions,\nfollowed by a mandatory fallback result (3 to 31 arguments, at most\n15 branches). Conditions are evaluated in order; only the selected\nresult is evaluated, and a NULL condition is not TRUE. All result\nexpressions must have the same physical type. Numeric SQL lowering\nrecords builtin result-domain promotions as explicit casts. This\noperation requires schema capability version 18.\nmodulo takes two same-domain integer or NUMERIC operands and returns the signed\nremainder (minInt modulo -1 is zero); a zero divisor rejects the write.\nin_list and not_in_list take one probe followed by 1 to 127 same-domain\ncandidates. The probe is evaluated once; NULL probes return UNKNOWN.\nA matching candidate wins over NULL candidates; otherwise a NULL\ncandidate makes the result UNKNOWN. These operations require schema\ncapability version 19.\n",
      "properties": {
        "op": {
          "$ref": "#/$defs/RelationalExpressionOp"
        },
        "type": {
          "$ref": "#/$defs/RelationalExpressionType"
        },
        "sql_type": {
          "$ref": "#/$defs/SQLBuiltinType",
          "description": "Numeric builtin result identity on numeric literals, arithmetic, negate, and cast (capability version 18), or required array element identity on sql_array literals including typed NULL (capability version 24)."
        },
        "numeric_modifier": {
          "$ref": "#/$defs/SQLNumericModifier",
          "description": "Optional precision/signed-scale coercion; accepted only on cast with type numeric and sql_type numeric. Requires reader capability version 23."
        },
        "value": {
          "description": "Typed literal value, including null."
        },
        "column": {
          "type": "string",
          "minLength": 1
        },
        "collation": {
          "type": "string",
          "description": "Optional binary or ASCII case-insensitive collation for string comparisons and in_list; aliases match ordered indexes."
        },
        "args": {
          "type": "array",
          "maxItems": 128,
          "items": {
            "$ref": "#/$defs/RelationalScalarExpression"
          }
        }
      }
    },
    "RelationalUniqueConstraint": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name"
      ],
      "description": "A named, ordered composite unique key. Validation status is maintained\nby the server. TTL expiry uses the distributed integrity coordinator.\nReferenced unique keys are nondeferrable.\n",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256
        },
        "origin": {
          "$ref": "#/$defs/RelationalUniqueConstraintOrigin"
        },
        "primary": {
          "type": "boolean",
          "description": "SQL primary-key identity. At most one per relational table; all key columns must be required and nonnullable."
        },
        "columns": {
          "type": "array",
          "minItems": 1,
          "maxItems": 32,
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "keys": {
          "type": "array",
          "minItems": 1,
          "maxItems": 32,
          "description": "Typed native unique keys. Specify either columns or keys.",
          "items": {
            "$ref": "#/$defs/RelationalIndexKey"
          }
        },
        "where": {
          "type": "array",
          "maxItems": 256,
          "description": "Conjunction restricting uniqueness to matching rows.",
          "items": {
            "$ref": "#/$defs/RelationalIndexPredicate"
          }
        },
        "nulls_not_distinct": {
          "type": "boolean",
          "description": "When true, NULL components compare equal for uniqueness."
        },
        "deferrable": {
          "type": "boolean",
          "description": "Permit uniqueness checks at transaction commit. Never eligible as an ON CONFLICT arbiter or a referenced foreign key target."
        },
        "timing": {
          "$ref": "#/$defs/ForeignKeyTiming"
        }
      }
    },
    "RelationalUniqueConstraintOrigin": {
      "type": "string",
      "enum": [
        "constraint",
        "index"
      ],
      "default": "constraint",
      "description": "Durable ownership kind. Index-owned uniqueness participates in ON CONFLICT inference but is not a named SQL constraint. Human-readable index descriptions never determine ownership."
    },
    "SQLArrayColumnSchema": {
      "type": "object",
      "additionalProperties": true,
      "required": [
        "type",
        "x-antfly-sql-type"
      ],
      "description": "JSON Schema property declaration for one typed SQL-array column in a\nrelational table. Use it as a root property of DocumentSchema.schema.\nThe element identity is mandatory; a JSON Schema `array` remains a JSON\ncolumn and is never inferred to be a SQL array. Column values use the\nlossless SQLArrayValue envelope: dimensions with lower bounds, flat\nrow-major values and explicit SQL NULL flags. Integer elements are\ndecimal strings, even when small. JSONB null and SQL NULL are distinct.\nFloat elements acquire their declared width before validation and\nstorage. Outer null represents a SQL NULL array when nullable is true.\nAdditional JSON Schema constraints apply to this envelope, not to\nPostgreSQL array subscripts. SQL array index keys and SQL DDL activation\nare not implied by accepting this storage schema.\n",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "sql_array"
          ]
        },
        "x-antfly-sql-type": {
          "$ref": "#/$defs/SQLArrayElementType"
        },
        "x-antfly-sql-numeric-modifier": {
          "$ref": "#/$defs/SQLNumericModifier",
          "x-go-type-skip-optional-pointer": false,
          "description": "Accepted only with numeric element identity. Applies assignment coercion to each non-NULL element while preserving dimensions and lower bounds. Requires reader capability version 23."
        },
        "nullable": {
          "type": "boolean",
          "default": false
        },
        "description": {
          "type": "string"
        }
      }
    },
    "SQLArrayElementType": {
      "type": "string",
      "description": "Bound SQL scalar or array-element identity, including numeric widths and exact NUMERIC. Never inferred from JSON value shape.",
      "enum": [
        "text",
        "int16",
        "int32",
        "int64",
        "float32",
        "float64",
        "boolean",
        "uuid",
        "jsonb",
        "numeric"
      ]
    },
    "SQLBuiltinType": {
      "type": "string",
      "description": "Exact PostgreSQL builtin identity for a relational root scalar column.\nSQL array columns use SQLArrayElementType for their element identity.\nSet the JSON Schema property's `x-antfly-sql-type` annotation to one of\nthese values. The underlying property type must match. SQL array storage\nis not implied by this annotation. Existing unannotated schemas retain\ntheir original domains.\nThe numeric identity uses an underlying number property and exact\nPostgreSQL NUMERIC semantics, never binary float. Submit finite values\nas JSON numeric lexemes or decimal strings; special values use strings\nNaN, Infinity and -Infinity. Const/enum finite numeric members must be\nJSON numbers, not strings. Bounds and multipleOf are exact decimals.\nPublic scalar NUMERIC schemas require reader capability version 22.\nTo constrain a NUMERIC scalar or SQL-array column, set the root\nproperty's `x-antfly-sql-numeric-modifier` annotation to an object with\nprecision (1..1000) and signed scale (-1000..1000). The annotation\nrequires numeric identity and reader capability version 23. Assignment\nrounds before constraints, indexes and generated dependents; overflow\nrejects the write. Restore verifies stored values without rounding.\n",
      "enum": [
        "text",
        "int16",
        "int32",
        "int64",
        "float32",
        "float64",
        "boolean",
        "uuid",
        "jsonb",
        "numeric"
      ]
    },
    "SQLNumericModifier": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "precision",
        "scale"
      ],
      "description": "PostgreSQL NUMERIC precision and signed scale. For arrays this describes every element, not dimensions. Absent means unconstrained NUMERIC.",
      "properties": {
        "precision": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000
        },
        "scale": {
          "type": "integer",
          "minimum": -1000,
          "maximum": 1000
        }
      }
    },
    "TableStorageMode": {
      "type": "string",
      "enum": [
        "document",
        "relational"
      ],
      "description": "Storage representation for the table. Omission selects \"document\".\n\"relational\" stores schema-bound typed rows and requires exactly one\nclosed document schema with declared properties. It implies\nenforce_types; explicitly setting enforce_types to false is invalid.\nExisting JSON document write and read APIs remain available. This\nsetting alone does not declare primary keys or unique constraints.\n"
    },
    "TemplateFieldMapping": {
      "type": "object",
      "additionalProperties": false,
      "description": "Field mapping used by a dynamic template. Dynamic templates match one physical field at a time and therefore do not accept multifields; use a DocumentFieldMapping in a document property's `x-antfly-field` annotation when named subfields are required.",
      "properties": {
        "type": {
          "$ref": "#/$defs/FieldMappingType"
        },
        "analyzer": {
          "type": "string",
          "description": "Analyzer name (e.g., \"standard\", \"keyword\", \"en\", \"html_analyzer\").\nUsed for text fields to control tokenization and normalization.\n"
        },
        "index": {
          "type": "boolean",
          "x-go-type-skip-optional-pointer": false,
          "description": "Whether to index the field. Omit to use the server default of true."
        },
        "store": {
          "type": "boolean",
          "default": false,
          "description": "Whether to store the field value (default false)"
        },
        "include_in_all": {
          "type": "boolean",
          "default": false,
          "description": "Whether to include in the _all field for cross-field search"
        },
        "sortable": {
          "type": "boolean",
          "default": false,
          "description": "Whether this exact scalar field can be used in order_by. Supported\nsortable mapping types are keyword, numeric/number/integer,\nboolean/bool, datetime/date/timestamp, and link. Analyzed text,\nsearch_as_you_type, geo, embedding, blob, html, object, and array\nfields are not directly sortable; use an exact scalar subfield such\nas title.keyword for sorted string pagination. When true, Antfly\nderives the internal typed doc-value structures required for exact\nsorting; users should not configure doc_values directly.\n"
        },
        "missing_null_policy": {
          "type": "string",
          "enum": [
            "missing_rejected",
            "nulls_ordered"
          ],
          "default": "missing_rejected",
          "description": "Missing/null sort policy for this mapped field. The default missing_rejected\nrejects missing or null native sort values. Opt in to nulls_ordered\nto sort missing/null values first ascending and last descending,\nwith JSON null in replayable sort cursor tuples. Native sorting\nrequires a complete producer proof for nullable physical layouts.\n"
        }
      }
    },
    "TtlConfig": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "duration"
      ],
      "description": "Automatic document-expiration policy for a table.",
      "properties": {
        "duration": {
          "type": "string",
          "description": "Expiration duration using Antfly's integer-component duration format.\nSupported units are `ns`, `us`, `ms`, `s`, `m`, `h`, and `d`;\nexamples include `90m`, `1h30m`, and `7d`.\n"
        },
        "field": {
          "type": "string",
          "default": "_timestamp",
          "minLength": 1,
          "description": "Timestamp field used as the expiration reference."
        }
      }
    }
  }
}