ChatEmbed chat.embed@1

Generated at from openvibe-contracts v0.419.0 and openvibe-sdk v0.161.0.

Version
1.0.0
Owner
chat
Visibility
public
Status
active
Compatibility
backward
Schema
https://openvibe.network/contracts/chat/embed.v1.json

chat.embed@1: one address preview under a chat message, the same shape for every client (OpenVibe.Chat, Live's chat and the Dock). A message carries `embeds` in the order the addresses appeared in its text, at most three; it is empty while the background job is still reading, and the client draws each one as the same card. The fields are data, never markup: a client escapes them (title, description, site_name, by) before drawing them. url is the address the writer sent, https only. image is an OpenVibe.Media address or null: another site's picture is never hot-linked. width and height are the picture's stated size, or 0. kind names what was found: an ordinary page (`link`), a video (`video`), a picture (`image`), a Live channel (`live`), a Pics picture (`picture`), a Design item (`design`), a Community post (`post`), a Network profile (`profile`) or a Games world (`game`). OpenVibe's own kinds are resolved through that service's public API, never by reading its page, and carry by (the person or channel the thing belongs to) and, for Live, live (whether the channel is broadcasting now); both are absent on an ordinary link. An agent-run embed carries the live run and event addresses, title and status.

Fields

FieldTypeRequiredDescriptionConstraints
kindenumyesWhat the address turned out to be; a client may draw the same card for every value.
  • one of "link", "video", "image", "live", "picture", "design", "post", "profile", "game", "agent-run"
urlstringyesThe https address the message carried, after the writer's trailing punctuation was dropped.
  • pattern ^https://
  • format uri
  • maxLength 2048
site_namestringyesThe site as it names itself (og:site_name, the provider's name, or the host).
  • maxLength 80
titlestringyes
  • minLength 1
  • maxLength 240
descriptionstringyesA short plain-text description, or an empty string when the source states none.
  • maxLength 300
imagestring | nullyesThe preview picture, only when it already lives on OpenVibe.Media; null when the source's picture would have to be hot-linked.
  • format uri
  • maxLength 2048
widthintegeryesThe picture's stated width in pixels, or 0.
  • minimum 0
  • maximum 100000
heightintegeryesThe picture's stated height in pixels, or 0.
  • minimum 0
  • maximum 100000
bystringOn OpenVibe's own kinds, the person or channel the thing belongs to (a Live channel's handle, a Video channel, a post's author, a profile's handle, a Games world's owner). Absent on an ordinary link.
  • maxLength 80
livebooleanOn a Live channel kind, whether it is broadcasting now. Absent on the other kinds.
run_urlstring
  • pattern ^https://
  • format uri
  • maxLength 2048
events_urlstring
  • pattern ^https://
  • format uri
  • maxLength 2048
statusenum
  • one of "queued", "running", "waiting", "needs_you", "succeeded", "failed", "stopped", "cancelled"

Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

Valid: agent-run
{
  "kind": "agent-run",
  "url": "https://openvibe.codes/runs/run_1",
  "site_name": "OpenVibe.Codes",
  "title": "Review repositories",
  "description": "",
  "image": null,
  "width": 0,
  "height": 0,
  "run_url": "https://openvibe.codes/api/v1/runs/run_1",
  "events_url": "https://openvibe.codes/api/v1/runs/run_1/events",
  "status": "running"
}
Valid: link
{
  "kind": "link",
  "url": "https://example.com/a-story",
  "site_name": "Example",
  "title": "A story & its title",
  "description": "What happened, in one short paragraph.",
  "image": "https://openvibe.media/objects/pic.jpg",
  "width": 640,
  "height": 360
}
Valid: live-channel
{
  "kind": "live",
  "url": "https://openvibe.live/@streamer",
  "site_name": "OpenVibe.Live",
  "title": "The Streamer",
  "description": "Live every Friday",
  "image": "https://openvibe.media/avatars/s.jpg",
  "width": 0,
  "height": 0,
  "by": "streamer",
  "live": true
}
Valid: picture-without-image
{
  "kind": "picture",
  "url": "https://openvibe.pics/i/abcd2345",
  "site_name": "OpenVibe.Pics",
  "title": "Harbour at dusk",
  "description": "",
  "image": null,
  "width": 1200,
  "height": 800
}
Rejected: agent-run
{
  "kind": "agent-run",
  "url": "https://openvibe.codes/runs/run_1",
  "site_name": "OpenVibe.Codes",
  "title": "Review repositories",
  "description": "",
  "image": null,
  "width": 0,
  "height": 0,
  "run_url": "https://openvibe.codes/api/v1/runs/run_1",
  "events_url": "http://insecure.test/events",
  "status": "running"
}
Rejected: bad-kind
{
  "kind": "article",
  "url": "https://example.com/article",
  "site_name": "Example",
  "title": "An article",
  "description": "",
  "image": null,
  "width": 0,
  "height": 0
}
Rejected: bad-live
{
  "kind": "live",
  "url": "https://openvibe.live/@streamer",
  "site_name": "OpenVibe.Live",
  "title": "The Streamer",
  "description": "",
  "image": null,
  "width": 0,
  "height": 0,
  "live": "yes"
}
Rejected: http-url
{
  "kind": "link",
  "url": "http://example.com/plain",
  "site_name": "Example",
  "title": "Plain",
  "description": "",
  "image": null,
  "width": 0,
  "height": 0
}
Rejected: no-title
{
  "kind": "link",
  "url": "https://example.com/no-title",
  "site_name": "Example",
  "description": "",
  "image": null,
  "width": 0,
  "height": 0
}

Validate

const contracts = require('openvibe-contracts');
contracts.validate('chat.embed@1', value);   // { valid, errors: [{ path, message }] }