{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://abyss.keyboard-hub.com/schemas/abyss-db/v1.json",
  "title": "Keyboard Abyss DB Schema",
  "description": "Persisted Keyboard Abyss row and JSON column schemas.",
  "$defs": {
    "UserLocale": {
      "description": "User locale preference.",
      "type": "string",
      "enum": ["en", "ja"],
      "x-zod-values-name": "userLocaleValues"
    },
    "UserRole": {
      "description": "Application user role.",
      "type": "string",
      "enum": ["user", "admin"],
      "x-zod-values-name": "userRoleValues"
    },
    "UserStatus": {
      "description": "Application user status.",
      "type": "string",
      "enum": ["active", "suspended"],
      "x-zod-values-name": "userStatusValues"
    },
    "OAuthProvider": {
      "description": "OAuth provider identifier.",
      "type": "string",
      "enum": ["github", "google", "apple", "x"],
      "x-zod-values-name": "oauthProviderValues"
    },
    "KeyboardStatus": {
      "description": "Keyboard publication status.",
      "type": "string",
      "enum": ["draft", "published"],
      "x-zod-values-name": "keyboardStatusValues"
    },
    "OwnershipClaimStatus": {
      "description": "Keyboard ownership claim review status.",
      "type": "string",
      "enum": ["pending", "approved", "rejected"],
      "x-zod-values-name": "ownershipClaimStatusValues"
    },
    "LayoutStatus": {
      "description": "Keyboard layout status.",
      "type": "string",
      "enum": ["default", "official", "not_suggested", "normal"],
      "x-zod-values-name": "layoutStatusValues"
    },
    "LayoutVariationStatus": {
      "description": "Keyboard layout variation status.",
      "type": "string",
      "enum": [
        "official",
        "suggested",
        "normal",
        "not_suggested",
        "deprecated"
      ],
      "x-zod-values-name": "layoutVariationStatusValues"
    },
    "KeymapStatus": {
      "description": "Keymap status.",
      "type": "string",
      "enum": ["default", "official", "suggested", "normal", "not_suggested"],
      "x-zod-values-name": "keymapStatusValues"
    },
    "KeymapVisibility": {
      "description": "Keymap visibility.",
      "type": "string",
      "enum": ["public", "private"],
      "x-zod-values-name": "keymapVisibilityValues"
    },
    "FirmwareFormat": {
      "description": "Firmware format identifier.",
      "type": "string",
      "enum": ["zmk", "via", "vial", "qmk"],
      "x-zod-values-name": "firmwareFormatValues"
    },
    "SQLiteBoolean": {
      "description": "SQLite boolean compatibility value.",
      "oneOf": [{ "const": 0 }, { "const": 1 }],
      "x-zod-schema-name": "sqliteBooleanSchema",
      "x-ts-type-name": "SQLiteBoolean"
    },
    "TimestampMs": {
      "description": "Millisecond timestamp used by persisted rows.",
      "type": "integer",
      "minimum": 0,
      "x-zod-schema-name": "timestampMsSchema"
    },
    "Ulid": {
      "description": "Canonical ULID string.",
      "type": "string",
      "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
      "x-zod-schema-name": "ulidSchema"
    },
    "KeyboardLinkIcon": {
      "description": "Keyboard information link icon preset identifier.",
      "type": "string",
      "enum": [
        "external",
        "build-guide",
        "official-site",
        "store",
        "design-repository",
        "keymap-repository",
        "ui-tool",
        "author-site",
        "author-social",
        "community",
        "documentation",
        "firmware",
        "gallery",
        "video",
        "support",
        "download"
      ],
      "x-zod-values-name": "keyboardLinkIconValues"
    },
    "KeyboardLink": {
      "description": "Keyboard link JSON column entry.",
      "type": "object",
      "additionalProperties": true,
      "required": ["label", "url"],
      "properties": {
        "label": { "type": "string", "minLength": 1, "maxLength": 80 },
        "url": { "type": "string", "format": "uri", "maxLength": 500 },
        "icon": { "$ref": "#/$defs/KeyboardLinkIcon" }
      }
    },
    "User": {
      "description": "User row.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "username",
        "display_name",
        "avatar_url",
        "bio",
        "website_url",
        "color_scheme",
        "role",
        "status",
        "created_at",
        "updated_at"
      ],
      "properties": {
        "id": { "$ref": "#/$defs/Ulid" },
        "username": { "type": "string", "minLength": 1 },
        "display_name": { "type": ["string", "null"] },
        "avatar_url": { "type": ["string", "null"] },
        "bio": { "type": ["string", "null"] },
        "website_url": { "type": ["string", "null"], "format": "uri" },
        "color_scheme": { "type": "string", "minLength": 1 },
        "role": { "$ref": "#/$defs/UserRole" },
        "status": { "$ref": "#/$defs/UserStatus" },
        "created_at": { "$ref": "#/$defs/TimestampMs" },
        "updated_at": { "$ref": "#/$defs/TimestampMs" }
      }
    },
    "OAuthAccount": {
      "description": "OAuth account row.",
      "x-zod-schema-name": "oauthAccountSchema",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "user_id",
        "provider",
        "provider_id",
        "provider_username",
        "provider_avatar_url",
        "is_public",
        "created_at",
        "updated_at"
      ],
      "properties": {
        "id": { "$ref": "#/$defs/Ulid" },
        "user_id": { "$ref": "#/$defs/Ulid" },
        "provider": { "$ref": "#/$defs/OAuthProvider" },
        "provider_id": { "type": "string", "minLength": 1 },
        "provider_username": { "type": ["string", "null"] },
        "provider_avatar_url": { "type": ["string", "null"], "format": "uri" },
        "is_public": { "$ref": "#/$defs/SQLiteBoolean" },
        "created_at": { "$ref": "#/$defs/TimestampMs" },
        "updated_at": { "$ref": "#/$defs/TimestampMs" }
      }
    },
    "Keyboard": {
      "description": "Keyboard row.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "created_by",
        "name",
        "slug",
        "description",
        "status",
        "type",
        "firmware_json",
        "links_json",
        "hashtags_json",
        "star_count",
        "owner_count",
        "created_at",
        "updated_at"
      ],
      "properties": {
        "id": { "$ref": "#/$defs/Ulid" },
        "created_by": { "$ref": "#/$defs/Ulid" },
        "name": { "type": "string", "minLength": 1 },
        "slug": { "type": "string", "minLength": 1 },
        "description": { "type": ["string", "null"] },
        "status": { "$ref": "#/$defs/KeyboardStatus" },
        "type": { "type": "string", "minLength": 1 },
        "firmware_json": {
          "type": "array",
          "items": { "type": "string", "minLength": 1 }
        },
        "links_json": {
          "type": "array",
          "maxItems": 6,
          "items": { "$ref": "#/$defs/KeyboardLink" }
        },
        "hashtags_json": {
          "type": "array",
          "maxItems": 8,
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60,
            "pattern": "^[^\\s#]+$"
          }
        },
        "preview_settings_json": {
          "oneOf": [
            { "type": "null" },
            {
              "type": "object",
              "description": "Optional keyboard-level preview defaults. Abyss treats unknown string values as unset when rendering.",
              "additionalProperties": false,
              "example": {
                "displayFormat": "keycap",
                "fontFamily": "\"Bangers\", system-ui, sans-serif",
                "keycapBorderColor": "#7aa7d9",
                "keycapColor": "#dcecff",
                "keycapTextColor": "#102033",
                "keycapPreset": "cherry",
                "layout": "jis",
                "locale": "ja",
                "modulePreset": "soft3d",
                "platform": "auto"
              },
              "properties": {
                "displayFormat": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 120,
                  "examples": [
                    "keycap",
                    "short",
                    "normal",
                    "icon",
                    "zmk",
                    "qmk"
                  ]
                },
                "fontFamily": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 240,
                  "examples": [
                    "system-ui, sans-serif",
                    "\"Bangers\", system-ui, sans-serif"
                  ]
                },
                "keycapColor": {
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$",
                  "examples": ["#fffaf0", "#dcecff"]
                },
                "keycapBorderColor": {
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$",
                  "examples": ["#b9aa8e", "#7aa7d9"]
                },
                "keycapTextColor": {
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$",
                  "examples": ["#17130d", "#102033"]
                },
                "keycapPreset": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 120,
                  "examples": [
                    "flat",
                    "minimal",
                    "cherry",
                    "dsa",
                    "roundedTop",
                    "deep3d"
                  ]
                },
                "layout": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 120,
                  "examples": ["us", "jis"]
                },
                "locale": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 120,
                  "examples": ["en", "ja", "ja-kana"]
                },
                "modulePreset": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 120,
                  "examples": ["flat", "soft3d", "deep3d", "blueprint"]
                },
                "platform": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 120,
                  "examples": [
                    "auto",
                    "default",
                    "macos",
                    "ios",
                    "windows",
                    "linux",
                    "android"
                  ]
                }
              }
            }
          ]
        },
        "cover_photo_id": {
          "type": ["string", "null"],
          "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
        },
        "star_count": { "type": "integer", "minimum": 0 },
        "owner_count": { "type": "integer", "minimum": 0 },
        "created_at": { "$ref": "#/$defs/TimestampMs" },
        "updated_at": { "$ref": "#/$defs/TimestampMs" }
      }
    },
    "KeyboardOwnershipClaim": {
      "description": "Keyboard ownership claim row.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "user_id",
        "keyboard_id",
        "status",
        "evidence",
        "admin_note",
        "reviewed_by",
        "created_at",
        "reviewed_at"
      ],
      "properties": {
        "id": { "$ref": "#/$defs/Ulid" },
        "user_id": { "$ref": "#/$defs/Ulid" },
        "keyboard_id": { "$ref": "#/$defs/Ulid" },
        "status": { "$ref": "#/$defs/OwnershipClaimStatus" },
        "evidence": { "type": ["string", "null"] },
        "admin_note": { "type": ["string", "null"] },
        "reviewed_by": {
          "type": ["string", "null"],
          "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
        },
        "created_at": { "$ref": "#/$defs/TimestampMs" },
        "reviewed_at": { "type": ["integer", "null"], "minimum": 0 }
      }
    },
    "KeyboardLayout": {
      "description": "Keyboard layout row.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "keyboard_id",
        "name",
        "description",
        "status",
        "modules_json",
        "default_variation_id",
        "created_by",
        "created_at",
        "updated_at"
      ],
      "properties": {
        "id": { "$ref": "#/$defs/Ulid" },
        "keyboard_id": { "$ref": "#/$defs/Ulid" },
        "name": { "type": "string", "minLength": 1 },
        "description": { "type": ["string", "null"] },
        "status": { "$ref": "#/$defs/LayoutStatus" },
        "modules_json": {
          "type": "array",
          "items": { "type": "string", "minLength": 1 }
        },
        "default_variation_id": {
          "type": ["string", "null"],
          "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
        },
        "created_by": { "$ref": "#/$defs/Ulid" },
        "created_at": { "$ref": "#/$defs/TimestampMs" },
        "updated_at": { "$ref": "#/$defs/TimestampMs" }
      }
    },
    "KeyboardLayoutPosition": {
      "description": "Keyboard layout physical key position.",
      "x-zod-expression": "keyboardLayoutKeyPositionSchema"
    },
    "KeyboardLayoutMatrix": {
      "description": "Keyboard layout matrix dimensions.",
      "x-zod-schema-name": "keymapMatrixSchema",
      "x-zod-expression": "keyboardLayoutMatrixSchema"
    },
    "LayoutVariationMeta": {
      "description": "Layout variation metadata JSON column.",
      "type": "object",
      "additionalProperties": false,
      "properties": { "matrix": { "$ref": "#/$defs/KeyboardLayoutMatrix" } }
    },
    "FirmwareDialect": {
      "description": "Firmware dialect metadata.",
      "x-zod-expression": "keyboardLayoutLayoutDialectSchema"
    },
    "KeyboardModuleAttributeConstraint": {
      "description": "Custom keyboard module attribute constraint.",
      "x-zod-schema-name": "moduleAttributeConstraintSchema",
      "x-zod-expression": "keyboardModuleDefinitionConstraintSchema"
    },
    "KeyboardModuleAttribute": {
      "description": "Custom keyboard module attribute.",
      "x-zod-schema-name": "moduleAttributeSchema",
      "x-zod-expression": "keyboardModuleDefinitionCustomAttributeSchema"
    },
    "KeyboardModuleVisual": {
      "description": "Keyboard module visual attribute.",
      "x-zod-expression": "keyboardModuleDefinitionSchema.shape.visual_attr.unwrap()"
    },
    "KeyboardModule": {
      "description": "Keyboard module definition.",
      "x-zod-expression": "keyboardModuleDefinitionSchema"
    },
    "KeyboardLayoutFeature": {
      "description": "Keyboard layout feature map.",
      "x-zod-expression": "keyboardLayoutFeaturesSchema"
    },
    "KeyboardLayoutDefinition": {
      "description": "Keyboard layout definition JSON document.",
      "type": "object",
      "additionalProperties": false,
      "required": ["name", "positions"],
      "properties": {
        "$schema": {
          "const": "https://abyss.keyboard-hub.com/schemas/keyboard-layout/v1.json"
        },
        "name": { "type": "string", "minLength": 1 },
        "displayName": { "type": "string", "minLength": 1 },
        "positions": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/$defs/KeyboardLayoutPosition" }
        },
        "matrix": { "$ref": "#/$defs/KeyboardLayoutMatrix" },
        "modules": {
          "type": "array",
          "default": [],
          "items": { "$ref": "#/$defs/KeyboardModule" }
        },
        "features": { "$ref": "#/$defs/KeyboardLayoutFeature", "default": {} },
        "firmwareDialect": { "$ref": "#/$defs/FirmwareDialect", "default": {} }
      }
    },
    "KeyboardLayoutVariation": {
      "description": "Keyboard layout variation row.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "layout_id",
        "positions_json",
        "modules_json",
        "features_json",
        "firmware_json",
        "status",
        "is_disabled",
        "created_by",
        "created_at"
      ],
      "properties": {
        "id": { "$ref": "#/$defs/Ulid" },
        "layout_id": { "$ref": "#/$defs/Ulid" },
        "positions_json": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/$defs/KeyboardLayoutPosition" }
        },
        "meta_json": {
          "anyOf": [
            { "$ref": "#/$defs/LayoutVariationMeta" },
            { "type": "null" }
          ]
        },
        "modules_json": {
          "type": "array",
          "items": { "$ref": "#/$defs/KeyboardModule" }
        },
        "features_json": { "$ref": "#/$defs/KeyboardLayoutFeature" },
        "firmware_json": { "$ref": "#/$defs/FirmwareDialect" },
        "changelog": { "type": ["string", "null"] },
        "status": { "$ref": "#/$defs/LayoutVariationStatus" },
        "is_disabled": { "$ref": "#/$defs/SQLiteBoolean" },
        "created_by": { "$ref": "#/$defs/Ulid" },
        "created_at": { "$ref": "#/$defs/TimestampMs" }
      }
    },
    "KeyboardPhoto": {
      "description": "Keyboard photo row.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "keyboard_id",
        "keymap_id",
        "uploader_id",
        "r2_key",
        "thumbnail_r2_key",
        "title",
        "description",
        "caption",
        "is_pinned",
        "show_in_overview",
        "layout_cover_id",
        "sort_order",
        "created_at",
        "updated_at"
      ],
      "properties": {
        "id": { "$ref": "#/$defs/Ulid" },
        "keyboard_id": { "$ref": "#/$defs/Ulid" },
        "keymap_id": {
          "type": ["string", "null"],
          "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
        },
        "uploader_id": { "$ref": "#/$defs/Ulid" },
        "r2_key": { "type": "string", "minLength": 1 },
        "thumbnail_r2_key": { "type": ["string", "null"] },
        "title": { "type": ["string", "null"] },
        "description": { "type": ["string", "null"] },
        "caption": { "type": ["string", "null"] },
        "is_pinned": { "$ref": "#/$defs/SQLiteBoolean" },
        "show_in_overview": { "$ref": "#/$defs/SQLiteBoolean" },
        "layout_cover_id": {
          "type": ["string", "null"],
          "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
        },
        "sort_order": { "type": "integer" },
        "created_at": { "$ref": "#/$defs/TimestampMs" },
        "updated_at": { "$ref": "#/$defs/TimestampMs" }
      }
    },
    "Keymap": {
      "description": "Keymap row.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "layout_variation_id",
        "user_id",
        "name",
        "description",
        "firmware_url",
        "visibility",
        "status",
        "star_count",
        "fork_count",
        "forked_from_id",
        "forked_from_version",
        "created_at",
        "updated_at"
      ],
      "properties": {
        "id": { "$ref": "#/$defs/Ulid" },
        "layout_variation_id": { "$ref": "#/$defs/Ulid" },
        "user_id": { "$ref": "#/$defs/Ulid" },
        "name": { "type": "string", "minLength": 1 },
        "description": { "type": ["string", "null"] },
        "firmware_url": {
          "type": ["string", "null"],
          "format": "uri",
          "maxLength": 500
        },
        "visibility": { "$ref": "#/$defs/KeymapVisibility" },
        "status": { "$ref": "#/$defs/KeymapStatus" },
        "star_count": { "type": "integer", "minimum": 0 },
        "fork_count": { "type": "integer", "minimum": 0 },
        "forked_from_id": {
          "type": ["string", "null"],
          "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
        },
        "forked_from_version": {
          "type": ["integer", "null"],
          "exclusiveMinimum": 0
        },
        "created_at": { "$ref": "#/$defs/TimestampMs" },
        "updated_at": { "$ref": "#/$defs/TimestampMs" }
      }
    },
    "KeymapLibraryEntry": {
      "description": "Keymap to Community Module mapping row.",
      "type": "object",
      "additionalProperties": false,
      "required": ["keymap_id", "library_entry_id", "created_at"],
      "properties": {
        "keymap_id": { "$ref": "#/$defs/Ulid" },
        "library_entry_id": { "$ref": "#/$defs/Ulid" },
        "created_at": { "$ref": "#/$defs/TimestampMs" }
      }
    },
    "KeymapVersion": {
      "description": "Keymap version row.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "keymap_id",
        "version",
        "data_json",
        "message",
        "created_at"
      ],
      "properties": {
        "id": { "$ref": "#/$defs/Ulid" },
        "keymap_id": { "$ref": "#/$defs/Ulid" },
        "version": { "type": "integer", "exclusiveMinimum": 0 },
        "data_json": { "type": "string", "minLength": 1 },
        "message": { "type": ["string", "null"] },
        "created_at": { "$ref": "#/$defs/TimestampMs" }
      }
    },
    "KeymapShareUrl": {
      "description": "Keymap share URL and OGP image row.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "short_hash",
        "keymap_id",
        "image_url",
        "image_r2_key",
        "image_expires_at",
        "created_at",
        "updated_at"
      ],
      "properties": {
        "short_hash": { "type": "string", "pattern": "^[a-z0-9]{8}$" },
        "keymap_id": { "$ref": "#/$defs/Ulid" },
        "image_url": { "type": "string", "format": "uri" },
        "image_r2_key": { "type": ["string", "null"] },
        "image_expires_at": { "$ref": "#/$defs/TimestampMs" },
        "created_at": { "$ref": "#/$defs/TimestampMs" },
        "updated_at": { "$ref": "#/$defs/TimestampMs" }
      }
    },
    "KeyboardStar": {
      "description": "Keyboard star row.",
      "type": "object",
      "additionalProperties": false,
      "required": ["user_id", "keyboard_id", "created_at"],
      "properties": {
        "user_id": { "$ref": "#/$defs/Ulid" },
        "keyboard_id": { "$ref": "#/$defs/Ulid" },
        "created_at": { "$ref": "#/$defs/TimestampMs" }
      }
    },
    "KeymapStar": {
      "description": "Keymap star row.",
      "type": "object",
      "additionalProperties": false,
      "required": ["user_id", "keymap_id", "created_at"],
      "properties": {
        "user_id": { "$ref": "#/$defs/Ulid" },
        "keymap_id": { "$ref": "#/$defs/Ulid" },
        "created_at": { "$ref": "#/$defs/TimestampMs" }
      }
    },
    "OAuthClient": {
      "description": "OAuth client row.",
      "x-zod-schema-name": "oauthClientSchema",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "owner_id",
        "name",
        "description",
        "website_url",
        "client_secret_hash",
        "redirect_uris",
        "allowed_scopes",
        "created_at"
      ],
      "properties": {
        "id": { "$ref": "#/$defs/Ulid" },
        "owner_id": { "$ref": "#/$defs/Ulid" },
        "name": { "type": "string", "minLength": 1 },
        "description": { "type": ["string", "null"] },
        "website_url": { "type": ["string", "null"], "format": "uri" },
        "client_secret_hash": { "type": "string", "minLength": 1 },
        "redirect_uris": {
          "type": "array",
          "minItems": 1,
          "items": { "type": "string", "format": "uri" }
        },
        "allowed_scopes": { "type": "string", "minLength": 1 },
        "created_at": { "$ref": "#/$defs/TimestampMs" }
      }
    }
  }
}