yads_spec_latest.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "yads spec",
  "description": "A schema for yads spec definitions.",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The fully qualified name of the table, including catalog and database/schema. Follows the format: [catalog].[database].[table]."
    },
    "version": {
      "type": "integer",
      "description": "Registry-assigned monotonic integer version for tracking changes."
    },
    "yads_spec_version": {
      "type": "string",
      "description": "Version of the yads specification format itself."
    },
    "description": {
      "type": "string",
      "description": "An optional description of the table defined by the spec."
    },
    "external": {
      "type": "boolean",
      "description": "Flag to emit a CREATE EXTERNAL statement from SQL DDL converters. Defaults to False.",
      "default": false
    },
    "metadata": {
      "type": "object",
      "description": "Optional metadata about the table as a simple key-value store."
    },
    "storage": {
      "type": "object",
      "description": "Defines the physical storage properties of the table.",
      "properties": {
        "format": {
          "type": "string",
          "description": "The table format (e.g., 'iceberg', 'orc', 'csv'). Translates to USING or STORED AS in SQL."
        },
        "location": {
          "type": "string"
        },
        "tbl_properties": {
          "type": "object",
          "description": "Key-value pairs for the TBLPROPERTIES clause."
        }
      },
      "additionalProperties": false
    },
    "partitioned_by": {
      "type": "array",
      "description": "Defines the table's partitioning scheme.",
      "items": {
        "$ref": "#/definitions/transformed_column"
      }
    },
    "table_constraints": {
      "type": "array",
      "description": "A list of table-level constraints, such as composite primary or foreign keys.",
      "items": {
        "$ref": "#/definitions/table_constraint"
      }
    },
    "columns": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/named_column"
      }
    }
  },
  "required": ["name", "version", "yads_spec_version", "columns"],
  "additionalProperties": false,
  "definitions": {
    "type": {
      "type": "string",
      "description": "The type of a column or field.",
      "enum": [
        "str",
        "STR",
        "string",
        "STRING",
        "text",
        "TEXT",
        "varchar",
        "VARCHAR",
        "char",
        "CHAR",
        "int8",
        "INT8",
        "uint8",
        "UINT8",
        "tinyint",
        "TINYINT",
        "byte",
        "BYTE",
        "int16",
        "INT16",
        "uint16",
        "UINT16",
        "smallint",
        "SMALLINT",
        "short",
        "SHORT",
        "int32",
        "INT32",
        "uint32",
        "UINT32",
        "int",
        "INT",
        "integer",
        "INTEGER",
        "int64",
        "INT64",
        "uint64",
        "UINT64",
        "bigint",
        "BIGINT",
        "long",
        "LONG",
        "float",
        "FLOAT",
        "float16",
        "FLOAT16",
        "float32",
        "FLOAT32",
        "float64",
        "FLOAT64",
        "double",
        "DOUBLE",
        "decimal",
        "DECIMAL",
        "numeric",
        "NUMERIC",
        "bool",
        "BOOL",
        "boolean",
        "BOOLEAN",
        "blob",
        "BLOB",
        "binary",
        "BINARY",
        "bytes",
        "BYTES",
        "date",
        "DATE",
        "time",
        "TIME",
        "datetime",
        "DATETIME",
        "timestamp",
        "TIMESTAMP",
        "timestamptz",
        "TIMESTAMPTZ",
        "timestamp_tz",
        "TIMESTAMP_TZ",
        "timestampltz",
        "TIMESTAMPLTZ",
        "timestamp_ltz",
        "TIMESTAMP_LTZ",
        "timestampntz",
        "TIMESTAMPNTZ",
        "timestamp_ntz",
        "TIMESTAMP_NTZ",
        "duration",
        "DURATION",
        "interval",
        "INTERVAL",
        "array",
        "ARRAY",
        "list",
        "LIST",
        "struct",
        "STRUCT",
        "record",
        "RECORD",
        "map",
        "MAP",
        "dictionary",
        "DICTIONARY",
        "json",
        "JSON",
        "geometry",
        "GEOMETRY",
        "geography",
        "GEOGRAPHY",
        "uuid",
        "UUID",
        "void",
        "VOID",
        "null",
        "NULL",
        "variant",
        "VARIANT",
        "tensor",
        "TENSOR"
      ]
    },
    "type_spec": {
      "type": "object",
      "description": "A type specification that can include type, parameters, and nested type definitions.",
      "properties": {
        "type": {
          "$ref": "#/definitions/type"
        },
        "params": {
          "type": "object",
          "description": "Parameters for parameterized types, such as precision and scale for decimals.",
          "properties": {
            "length": {
              "type": "integer",
              "description": "The length of a string or binary column."
            },
            "bits": {
              "type": "integer",
              "description": "Bit width for the type. One of 8, 16, 32, 64, 128, 256.",
              "enum": [8, 16, 32, 64, 128, 256]
            },
            "signed": {
              "type": "boolean",
              "description": "Signedness for integer types. True for signed, False for unsigned. Defaults to True.",
              "default": true
            },
            "precision": {
              "type": "integer",
              "description": "The precision of a decimal column."
            },
            "scale": {
              "type": "integer",
              "description": "The scale of a decimal column. May be negative to indicate rounding to the left of the decimal point."
            },
            "unit": {
              "type": "string",
              "description": "Time precision unit. One of s, ms, us, ns.",
              "enum": ["s", "ms", "us", "ns"]
            },
            "tz": {
              "type": "string",
              "description": "IANA timezone string for timestamp with timezone (timestamptz)."
            },
            "size": {
              "type": "integer",
              "description": "The maximum number of elements in an array (fixed-size)."
            },
            "keys_sorted": {
              "type": "boolean",
              "description": "Whether the map type has sorted keys.",
              "default": false
            },
            "interval_start": {
              "type": "string",
              "description": "The start of an interval for an interval column.",
              "enum": [
                "year",
                "YEAR",
                "month",
                "MONTH",
                "day",
                "DAY",
                "hour",
                "HOUR",
                "minute",
                "MINUTE",
                "second",
                "SECOND"
              ]
            },
            "interval_end": {
              "type": "string",
              "description": "The end of an interval for an interval column.",
              "enum": [
                "year",
                "YEAR",
                "month",
                "MONTH",
                "day",
                "DAY",
                "hour",
                "HOUR",
                "minute",
                "MINUTE",
                "second",
                "SECOND"
              ]
            },
            "shape": {
              "type": "array",
              "description": "Fixed dimensions for tensor type.",
              "items": {
                "type": "integer",
                "minimum": 1
              },
              "minItems": 1
            },
            "additionalProperties": false
          }
        },
        "element": {
          "description": "The type of the elements in an array or tensor.",
          "$ref": "#/definitions/type_spec"
        },
        "fields": {
          "type": "array",
          "description": "The fields of a struct.",
          "items": {
            "$ref": "#/definitions/named_column"
          }
        },
        "key": {
          "description": "The type of a key in a map.",
          "$ref": "#/definitions/type_spec"
        },
        "value": {
          "description": "The type of a value in a map.",
          "$ref": "#/definitions/type_spec"
        }
      },
      "required": ["type"]
    },
    "column": {
      "allOf": [
        { "$ref": "#/definitions/type_spec" },
        {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Optional name of the column or field."
            },
            "description": {
              "type": "string",
              "description": "Optional description of the column or field."
            },
            "constraints": {
              "$ref": "#/definitions/constraints"
            },
            "generated_as": {
              "$ref": "#/definitions/transformed_column"
            },
            "metadata": {
              "type": "object"
            }
          }
        }
      ]
    },
    "transformed_column": {
      "type": "object",
      "description": "A column that may have a transformation function applied to it. Used for both partitioning/clustering and generated column specifications.",
      "properties": {
        "column": { "type": "string" },
        "transform": { "type": "string" },
        "transform_args": {
            "type": "array",
            "description": "A list of unnamed arguments for the transformation function."
        }
      },
      "required": ["column"],
      "additionalProperties": false
    },
    "named_column": {
      "type": "object",
      "description": "A named column definition.",
      "allOf": [
        { "$ref": "#/definitions/column" },
        { "required": ["name"] }
      ]
    },
    "table_constraint": {
      "type": "object",
      "description": "A table-level constraint, such as a primary or foreign key.",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["primary_key", "foreign_key"]
        },
        "name": {
          "type": "string"
        },
        "columns": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "references": {
          "type": "object",
          "properties": {
            "table": {
              "type": "string"
            },
            "columns": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": ["table"],
          "additionalProperties": false
        }
      },
      "required": ["type", "columns", "name"],
      "additionalProperties": false
    },
    "constraints": {
      "type": "object",
      "properties": {
        "not_null": {
          "type": "boolean",
          "description": "Whether the column is not nullable."
        },
        "primary_key": {
          "type": "boolean",
          "description": "Whether the column is a primary key."
        },
        "identity": {
          "type": "object",
          "description": "Defines an identity column, often used for auto-incrementing keys.",
          "properties": {
            "always": {
              "type": "boolean",
              "description": "Whether the identity column is always generated.",
              "default": true
            },
            "start": {
              "type": "integer",
              "description": "The starting value for the identity column."
            },
            "increment": {
              "type": "integer",
              "description": "The increment value for the identity column."
            }
          }
        },
        "foreign_key": {
          "type": "object",
          "description": "Defines a foreign key constraint.",
          "properties": {
            "name": {
              "type": "string",
              "description": "The name of the foreign key constraint."
            },
            "references": {
              "type": "object",
              "description": "The referenced table and columns for the foreign key constraint.",
              "properties": {
                "table": {
                  "type": "string",
                  "description": "The name of the referenced table."
                },
                "columns": {
                  "type": "array",
                  "description": "The columns in the referenced table that are referenced by the foreign key constraint.",
                  "items": {
                    "type": "string",
                    "description": "The name of the referenced column."
                  }
                }
              },
              "required": ["table"]
            }
          },
          "required": ["references"],
          "additionalProperties": false
        },
        "default": {
          "description": "The default value for the column."
        }
      },
      "additionalProperties": false
    }
  }
}