Project

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/craaft-io/json-schema/craaft-io-project-schema.json",
  "title": "Project",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/craaft-io-openapi.yml#/components/schemas/Project",
  "type": "object",
  "required": [
    "id",
    "workspaceId",
    "name",
    "createdAt",
    "updatedAt"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "workspaceId": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string",
      "maxLength": 200
    },
    "description": {
      "type": "string"
    },
    "brief": {
      "type": "string",
      "maxLength": 20000,
      "description": "The board brief (Markdown): goals, constraints, voice, decisions and links for anyone working on the board. On GET and PATCH /projects/{id} only; the list leaves it out. Every card's prompt ends with it."
    },
    "isFavorite": {
      "type": "boolean"
    },
    "publicToken": {
      "type": "string",
      "description": "Non-empty when public sharing is on"
    },
    "backgroundImage": {
      "type": "string"
    },
    "backgroundColor": {
      "type": "string",
      "description": "Board background hex color (#rrggbb), empty when unset; mutually exclusive with backgroundImage"
    },
    "colorScheme": {
      "type": "string"
    },
    "textColor": {
      "type": "string",
      "enum": [
        "dark",
        "light"
      ]
    },
    "showMilestones": {
      "type": "boolean",
      "description": "Whether the board's top bar shows the milestones button. Off on new boards (since 28 October 2026); boards made before then keep it on unless changed."
    },
    "showArchived": {
      "type": "boolean",
      "description": "Whether the board's top bar shows the archived cards button. Off on new boards (since 28 October 2026); boards made before then keep it on unless changed."
    },
    "showFiles": {
      "type": "boolean",
      "description": "Whether the board's top bar shows the files button. Off on new boards (since 28 October 2026); boards made before then keep it on unless changed."
    },
    "showStandup": {
      "type": "boolean",
      "description": "Whether the board's top bar shows the standup button. Off on new boards (since 28 October 2026); boards made before then keep it on unless changed."
    },
    "showActivity": {
      "type": "boolean",
      "description": "Whether the board's top bar shows the activity button. Off by default. The /projects/{id}/activity feed answers either way."
    },
    "myRole": {
      "type": "string",
      "enum": [
        "owner",
        "admin",
        "member"
      ],
      "description": "Caller's role in the project's *workspace* (distinct from myBoardRole)."
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "workspace"
      ],
      "description": "`private` (default): only users with an explicit grant (plus\nworkspace owners/admins) see the board. `workspace`: every\nworkspace member is an implicit contributor.\n"
    },
    "myBoardRole": {
      "type": "string",
      "enum": [
        "admin",
        "contributor"
      ],
      "description": "Caller's effective role on the board. Workspace owners and admins\nare always `admin`; explicit grants resolve to `admin` or\n`contributor`; on a `workspace`-visibility board, plain workspace\nmembers default to `contributor`.\n"
    },
    "canUploadAttachments": {
      "type": "boolean",
      "description": "Whether cards on this board accept file attachments. Reflects the\nboard's *workspace* plan (Pro), NOT the caller's own plan - so a\nFree user collaborating on a Pro workspace's board sees `true`.\nMatches the server's upload gate; the SPA uses it to show/hide the\nattachment dropzone.\n"
    },
    "totalCards": {
      "type": "integer"
    },
    "columnCounts": {
      "type": "object",
      "additionalProperties": {
        "type": "integer"
      }
    },
    "workspaceName": {
      "type": "string",
      "description": "Workspace display name; populated on list responses."
    },
    "members": {
      "type": "array",
      "description": "Capped avatar-stack preview on list responses only.",
      "items": {
        "$ref": "#/$defs/ProjectMemberPreview"
      }
    },
    "columns": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Column"
      }
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    }
  },
  "$defs": {
    "Column": {
      "type": "object",
      "required": [
        "id",
        "key",
        "title",
        "position"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "key": {
          "type": "string",
          "description": "Stable identifier for cards.column"
        },
        "title": {
          "type": "string",
          "maxLength": 80
        },
        "color": {
          "type": "string",
          "description": "Optional palette token; empty for default"
        },
        "position": {
          "type": "number"
        },
        "isDone": {
          "type": "boolean"
        },
        "cardLimit": {
          "type": [
            "integer",
            "null"
          ]
        }
      }
    },
    "ProjectMemberPreview": {
      "type": "object",
      "required": [
        "id",
        "name",
        "avatarUrl"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "name": {
          "type": "string"
        },
        "avatarUrl": {
          "type": "string",
          "description": "Empty when no upload; otherwise /api/v1/users/{id}/avatar"
        }
      }
    }
  }
}