theCard: Person/Topic Description Format

Tinode uses theCard to store and transmit descriptions of people and topics. The format is conceptually similar to vCard 3.0.

When JSON is used to represent theCard data, it does it differently than jCard. theCard and jCard are incompatible. The main difference is that theCard uses objects to represent logically related data while jCard uses ordered arrays.

theCard is structured as an object:

{
  fn: "John Doe", // string, formatted name of the person or topic.
  photo: { // object, avatar photo; either 'data' or 'ref' must be present, all other fields are optional.
    type: "jpeg", // string, MIME type but with 'image/' dropped.
    data: "Rt53jUU...iVBORw0KGgoA==", // string, base64-encoded binary image data
    ref: "https://api.tinode.co/file/s/abcdef12345.jpg", // string, URL of the image.
    width: 512, // integer, image width in pixels.
    height: 512, // integer, image height in pixels.
    size: 123456 // integer, image size in bytes.
  },
  note: "Some notes", // string, description of a person or a topic.
  //
  // None of the following fields are implemented by any known client:
  //
  n: { // object, person's structured name.
    surname: "Miner", // surname or last or family name.
    given: "Coal", // first or given name.
    additional: "Diamond", // additional name, such as middle name or patronymic.
    prefix: "Dr.", // prefix, such as honorary title or gender designation.
    suffix: "Jr.", // suffix, such as 'Jr' or 'II'.
  },
  org: { // object, organization the person or topic belongs to.
    fn: "Most Evil Corp", // string, formatted name of the organisation.
    title: "CEO", // string, person's job title at the organisation.
  },
  comm: [ // array of objects defining means of communication with the the person or topic.
    {
      des: ["home", "voice"], // contact designation, optional.
      proto: "tel", // communication protocol, required
      value: "+17025551234" // phone number.
    },
    {
      des: ["work"],
      proto: "email",
      value: "[email protected]", // email address
    },
    {
      des: ["other"],
      proto: "tinode",
      value: "tinode:topic/usrRkDVe0PYDOo", // tinode ID URI, may include server address.
    },
    {
      proto: "http", // should be used for either http or https website addresses.
      value: "https://tinode.co", // actual address of a website.
    }, ...
  ],
  bday: { // object, person's birthday.
    y: 1970, // integer, year
    m: 1, // integer, month 1..12
    d: 15 // integer, day 1..31
  },
}

All fields are optional. Tinode clients currently use only fn, photo, org, note, comm fields. If other fields are needed in the future, then they will be adopted from the correspondent vCard fields.