{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "imports-v2/cards.json",
  "title": "Cards",
  "description": "The current state of a card: where it is now and what it says. Everything that grows around a card is a separate resource that points back at it: tags, members, checklists, comments, files, links, history and activities. A card needs a board, a column of that board and a type; without `lane_ref` it goes to the first lane. The cards of one column keep the order of their records, so they stand on the board in that order. Keep the record small and put large collections in their own resources.",
  "type": "object",
  "properties": {
    "external_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "description": "Your own identifier of the record, for example `k-mrr`, unique within the resource across all of its files and case sensitive. Other records refer to this one by it. The import also keeps it as the external id of the object it creates."
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "The card's name, for example `Monthly recurring revenue`. Up to 1024 characters."
    },
    "description": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "format": {
          "type": "string",
          "enum": [
            "plain_text",
            "markdown",
            "html"
          ]
        },
        "text": {
          "type": "string"
        }
      },
      "required": [
        "format",
        "text"
      ],
      "additionalProperties": false,
      "x-link-tokens": [
        {
          "scheme": "attachment",
          "resource": "attachments"
        },
        {
          "scheme": "card",
          "resource": "cards"
        },
        {
          "scheme": "document",
          "resource": "documents"
        }
      ],
      "description": "The card's main text; give the format with the text."
    },
    "board_ref": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "x-ref": "boards",
      "description": "The board the card is on. Give the external_id of a `boards` record."
    },
    "column_ref": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "x-ref": "columns",
      "description": "The column the card is in now. It must be a column of the board in `board_ref`."
    },
    "lane_ref": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 512,
      "x-ref": "lanes",
      "description": "The lane the card is in. It must be a lane of the board in `board_ref`; without it the card goes to the first lane of the board, that is the first `lanes` record of that board.",
      "x-default-text": "the first lane of the board"
    },
    "type_ref": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "x-ref": "card_types",
      "description": "The card type, by the external_id of a `card_types` record."
    },
    "owner_ref": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "x-ref": "users",
      "description": "The person the card is for, shown in the card header as its owner (requester); usually whoever created the card, for example the reporter of a task. Give the external_id of a `users` record."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$",
      "description": "When the card was created, for example `2026-01-12T09:30:00Z`."
    },
    "asap": {
      "type": "boolean",
      "description": "Marks the card as urgent so it stands out on the board.",
      "default": false
    },
    "due_date": {
      "anyOf": [
        {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "precision": {
                  "type": "string",
                  "enum": [
                    "date"
                  ],
                  "description": "Always date."
                },
                "value": {
                  "type": "string",
                  "format": "date",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                }
              },
              "required": [
                "precision",
                "value"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "precision": {
                  "type": "string",
                  "enum": [
                    "date_time"
                  ],
                  "description": "Always date_time."
                },
                "value": {
                  "type": "string",
                  "format": "date-time",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$"
                }
              },
              "required": [
                "precision",
                "value"
              ],
              "additionalProperties": false
            }
          ]
        },
        {
          "type": "null"
        }
      ],
      "description": "The card's deadline. Either a day, `{\"precision\": \"date\", \"value\": \"2026-03-31\"}`, or a moment, `{\"precision\": \"date_time\", \"value\": \"2026-03-31T17:30:00Z\"}`. A day stays a day; no time is added. A moment keeps only its hours and minutes: the card is due at the end of that minute (17:30:59), as when someone sets a due time in the app."
    },
    "expires_later": {
      "type": "boolean",
      "description": "Marks `due_date` as a \"no later than\" deadline: the work may finish earlier, but not after that date. In the app it is the \"Expires later\" option of the due date, and the deadline on the card shows a mark. It matters only when the card has a `due_date`; the default is false.",
      "default": false
    },
    "size": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "value": {
              "type": "number",
              "description": "Numeric size."
            },
            "unit": {
              "type": "string",
              "maxLength": 256,
              "description": "Unit of `value`, for example `SP` for story points or `h` for hours. Without `display` the card shows the value and the unit together, for example `3 SP`."
            },
            "display": {
              "type": "string",
              "maxLength": 267,
              "description": "The size as the card shows it, for example `3 SP`, or `XL` for a T-shirt size. Give `value`, `display` or both: without `display` the card shows `value` and `unit` together; a size that is not a number, such as `XL`, needs only `display`. Charts count only `value`."
            }
          },
          "required": [],
          "additionalProperties": false,
          "anyOf": [
            {
              "required": [
                "value"
              ]
            },
            {
              "required": [
                "display"
              ]
            }
          ]
        },
        {
          "type": "null"
        }
      ],
      "description": "Card size: a number with an optional unit and display text, for example 3, SP, \"3 SP\". A size can also be text only, for example {\"display\": \"XL\"}; value or display must be given."
    },
    "estimate_workload": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 99999.99,
      "description": "Estimated work in hours, for example 12.5, with at most two decimal places."
    },
    "planned_start": {
      "anyOf": [
        {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "precision": {
                  "type": "string",
                  "enum": [
                    "date"
                  ],
                  "description": "Always date."
                },
                "value": {
                  "type": "string",
                  "format": "date",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                }
              },
              "required": [
                "precision",
                "value"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "precision": {
                  "type": "string",
                  "enum": [
                    "date_time"
                  ],
                  "description": "Always date_time."
                },
                "value": {
                  "type": "string",
                  "format": "date-time",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$"
                }
              },
              "required": [
                "precision",
                "value"
              ],
              "additionalProperties": false
            }
          ]
        },
        {
          "type": "null"
        }
      ],
      "description": "When work on the card is planned to start; with `planned_end` it places the card on the timeline of its space. Give a day, `{\"precision\": \"date\", \"value\": \"2026-04-01\"}`, which starts at the start hour of the space's timeline (9:00 by default), or a moment, `{\"precision\": \"date_time\", \"value\": \"2026-04-01T10:00:00Z\"}`. `planned_end` needs it, and a dependency in `card_planned_relations` needs both dates on both cards."
    },
    "planned_end": {
      "anyOf": [
        {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "precision": {
                  "type": "string",
                  "enum": [
                    "date"
                  ],
                  "description": "Always date."
                },
                "value": {
                  "type": "string",
                  "format": "date",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                }
              },
              "required": [
                "precision",
                "value"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "precision": {
                  "type": "string",
                  "enum": [
                    "date_time"
                  ],
                  "description": "Always date_time."
                },
                "value": {
                  "type": "string",
                  "format": "date-time",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$"
                }
              },
              "required": [
                "precision",
                "value"
              ],
              "additionalProperties": false
            }
          ]
        },
        {
          "type": "null"
        }
      ],
      "description": "Planned end of the work. Allowed only together with `planned_start`."
    },
    "completed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$",
      "description": "When the work on the card was completed."
    },
    "key": {
      "type": "string",
      "minLength": 3,
      "pattern": "^[A-Z][A-Z0-9_]{1,15}-(?:[1-9][0-9]{0,8}|1[0-9]{9}|20[0-9]{8}|21[0-3][0-9]{7}|214[0-6][0-9]{6}|2147[0-3][0-9]{5}|21474[0-7][0-9]{4}|214748[0-2][0-9]{3}|2147483[0-5][0-9]{2}|21474836[0-3][0-9]|214748364[0-7])$",
      "description": "The key the card is known by now, as PREFIX-NUMBER, for example `KPI_MRD_X7Q4-1`. NUMBER is a whole number from 1 to 2147483647 without leading zeros, so `KPI-7` is valid and `KPI-007` is not. PREFIX is the `key` of the space or folder that issues it, so exactly one space or folder must have it. Leave it out for a card without a key. Keys are unique. Earlier keys of a card cannot be imported."
    },
    "subscriber_refs": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 512,
        "x-ref": "users"
      },
      "uniqueItems": true,
      "description": "The users who follow the card and get notified about its changes and moves, by the external_id of `users` records, for example `[\"u-ava\", \"u-omar\"]`. Each user at most once.",
      "default": []
    },
    "tag_refs": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 512,
        "x-ref": "tags"
      },
      "uniqueItems": true,
      "description": "The tags on the card, by the external_id of `tags` records, for example `[\"t-revenue\"]`. Each tag at most once.",
      "default": []
    },
    "properties": {
      "type": "object",
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          },
          {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "precision": {
                    "type": "string",
                    "enum": [
                      "date"
                    ],
                    "description": "Always date."
                  },
                  "value": {
                    "type": "string",
                    "format": "date",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  }
                },
                "required": [
                  "precision",
                  "value"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "precision": {
                    "type": "string",
                    "enum": [
                      "date_time"
                    ],
                    "description": "Always date_time."
                  },
                  "value": {
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$"
                  }
                },
                "required": [
                  "precision",
                  "value"
                ],
                "additionalProperties": false
              }
            ]
          },
          {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            },
            "uniqueItems": true
          }
        ]
      },
      "description": "The values of the custom properties of the card. Each key is the `external_id` of a `custom_properties` record and each value has the shape the type of that property decides: text for `string`, `multiline_string`, `email`, `url` and `phone`; a number for `number`; `true` or `false` for `checkbox`; a date value for `date`, for example `{\"precision\": \"date\", \"value\": \"2026-03-01\"}` or, with a time, `{\"precision\": \"date_time\", \"value\": \"2026-04-15T09:00:00Z\"}`; the `external_id` of an option (an item of `options`) of the same property for `select`, and a list of them, each once, for `multi_select`; the `external_id` of a `users` record for `user`, and a list of them, each once, for `multi_user`; the `external_id` of a `custom_directory_records` record of the directory of the property for `directory`; a whole number from 1 to the `count` of the property for a `vote` with a rating, and one emoji of the set for a `vote` with a set of emojis. A property of type `attachment` has no value here: its files are `attachments` with `property_ref`. A property the card has no value for is left out."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$",
      "description": "When the record was last changed, for example `2026-02-10T15:30:00Z`.",
      "x-default-text": "created_at"
    },
    "updated_by_ref": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 512,
      "x-ref": "users",
      "description": "The user who made the last change, by the external_id of a `users` record. Leave it out or use null when unknown."
    },
    "archived": {
      "type": "boolean",
      "description": "Whether the record is archived, that is hidden from active lists but kept. The default is false.",
      "default": false
    }
  },
  "required": [
    "external_id",
    "title",
    "board_ref",
    "column_ref",
    "type_ref",
    "owner_ref",
    "created_at"
  ],
  "additionalProperties": false,
  "allOf": [
    {
      "dependencies": {
        "planned_end": [
          "planned_start"
        ]
      }
    }
  ]
}