mirror of
https://github.com/tinode/chat.git
synced 2026-05-07 20:12:42 +00:00
or-else
65 lines
2.9 KiB
Markdown
65 lines
2.9 KiB
Markdown
# theCard: Person/Topic Description Format
|
|
|
|
Tinode uses `theCard` to store and transmit descriptions of people and topics. The format is conceptually similar to [vCard](https://www.rfc-editor.org/rfc/rfc6350.txt) 3.0.
|
|
|
|
When `JSON` is used to represent `theCard` data, it does it differently than [jCard](https://tools.ietf.org/html/rfc7095). `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:
|
|
|
|
```js
|
|
{
|
|
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: "alice@example.com", // 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](https://www.rfc-editor.org/rfc/rfc6350.txt) fields.
|