Skip to main content
The raw JSON Schema is available at already.so/schema. The Already Session Schema defines the canonical format for sessions. A session document has 6 top-level fields:

​
Session metadata

Session identity, timestamps, recording configuration, environment, and project management.
​
string (uuid)
required
Session identifier
​
string (date-time)
required
Creation timestamp
​
string (date-time)
End timestamp
​
number
Duration in seconds
​
string
Session title
​
string
Session description
​
string
One of: in_session, uploading, todo, in_progress, needs_feedback, done, cancelled
​
string
Assignee identifier
​
string
Assignee username
​
string[]
Label names
​
integer
1 (highest) to 5 (lowest)
​
string
One of: electron, web, ios, android
​
string
Platform version string
​
boolean
Whether session includes video
​
boolean
Whether session includes audio
​
string
One of: h264, h265, vp9, av1
​
integer
Video width in pixels
​
integer
Video height in pixels
​
number
Frames per second
​
string
Operating system (e.g. macOS, Windows, iOS, Android)
​
string
OS version string
​
string
Device name (e.g. MacBook Pro 16-inch, iPhone 15 Pro)
​
integer
Screen width in pixels
​
integer
Screen height in pixels
​
number
Screen scale factor (e.g. 2 for Retina)
​
string
Team identifier
​
string
Creator identifier

​
Timeline events

Capture events recorded during the session, sorted by timestamp. Every event has timestamp + type. Other fields depend on the event type.

​
Event types

​
Common fields

These fields are present on most events:
​
number
required
Seconds from session start
​
string
required
Event type (see list above)
​
string
Text content. Used by: text_typed, transcription, annotation, console_error
​
number
X coordinate. Used by: mouse_click, click, touch, annotation
​
number
Y coordinate. Used by: mouse_click, click, touch, annotation
​
string
URL. Used by: page_navigation, click, annotation, console_error, network_request
​
string
ID of a media item. Used by: snapshot, annotation

​
Type-specific fields

​
string
Application name (window_focus)
​
string
Window title (window_focus)
​
string
macOS bundle ID or Windows process name (window_focus)
​
integer
Display index (window_focus)
​
string
Page title (page_navigation)
​
string
Referrer URL (page_navigation)
​
string
Current screen/activity (screen_change)
​
string
Previous screen (screen_change)
​
string
foreground or background (app_state)
​
string
Key identifier (keystroke)
​
string
left, right, or middle (mouse_click)
​
string
Text highlighted by the user (text_selected)
​
string
CSS selector path (click, annotation)
​
string
HTML tag name (click, annotation)
​
string
Visible text of the element (click, annotation)
​
object
Element bounding box with x, y, width, height (click, annotation)
​
string
React component tree (click, annotation)
​
string
Element class list (click, annotation)
​
string
ARIA info (click, annotation)
​
string
Text around the element (click, annotation)
​
boolean
Fixed/sticky positioning (click, annotation)
​
string
One of: tap, double_tap, long_press, swipe, pinch, rotate (touch)
​
number[][]
Multi-touch points as [[x,y], ...] (touch)
​
number
Audio start time in seconds (transcription)
​
number
Audio end time in seconds (transcription)
​
string
error, warn, or info (console_error)
​
string
Stack trace (console_error)
​
string
HTTP method (network_request)
​
integer
HTTP status code (network_request)
​
number
Request duration in ms (network_request)

​
Media

Media files (video, audio, images) associated with the session. Referenced by timeline events via mediaRef.
​
string
required
Media identifier, referenced by timeline events
​
string
required
One of: video, audio, image
​
string
required
File name
​
string
One of: recording, snapshot, annotation, smart, pasted, converted
​
string
MIME type
​
string
Cloud storage URL
​
integer
Width in pixels
​
integer
Height in pixels
​
number
Duration in seconds (video/audio)
​
integer
File size in bytes
​
string (date-time)
Creation timestamp

​
Comments

Threaded discussion on the session.
​
string
required
Comment identifier
​
string (date-time)
required
Creation timestamp
​
string
required
Author identifier
​
string
required
Comment text
​
string (date-time)
Last update timestamp
​
string
Author username
​
string
Parent comment ID for threaded replies

​
Notes

Rich-text notes. Content is an array of nodes (paragraphs, headings, images, etc.) in Tiptap JSON format.
​
object[]
Array of content nodes, each with a required type field (e.g. paragraph, heading, image)