RaycastREFERENCE
Start building
DESIGN REFERENCE

Objects give the
interface its shape.

A strict local schema supports predictable rendering, safe links, realistic fixtures, and testable recovery.

Public evidence18 Sep 2026Observed sources. Explicit local contracts.

The public model

Collections own filters, order, count and empty states. Records own identity and content. A route selects a record; a dialog owns only a temporary interaction. Source facts, reconstructed contracts and authored fixtures remain separate fields.

Extension

Extension schema fields
FieldType / limitsRequired
id{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"}Yes
slug{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"}Yes
name{"type":"string","minLength":1,"maxLength":140}Yes
summary{"anyOf":[{"type":"string","minLength":1,"maxLength":400},{"type":"null"}]}Yes
publisher{"anyOf":[{"$ref":"#/$defs/Person"},{"type":"null"}]}Yes
category{"type":"string","enum":["productivity","developer-tools","communication","design","utilities"]}Yes
platforms{"type":"array","items":{"type":"string","enum":["macos","windows"]},"minItems":1,"maxItems":2,"uniqueItems":true}Yes
iconAssetId{"anyOf":[{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},{"type":"null"}]}Yes
publicUrl{"$ref":"#/$defs/OfficialPublicHref"}Yes
commands{"type":"array","items":{"$ref":"#/$defs/Command"},"minItems":0,"maxItems":60}Yes
access{"type":"string","enum":["public","sign-in-required","unavailable"]}Yes
updatedAt{"type":"string","minLength":20,"maxLength":30,"format":"date-time","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"}Yes
locale{"type":"string","minLength":2,"maxLength":20,"pattern":"^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"}Yes
tags{"type":"array","items":{"type":"string","minLength":1,"maxLength":32},"minItems":0,"maxItems":10,"uniqueItems":true}Yes
downloadCount{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}Yes
revision{"type":"integer","minimum":1,"maximum":2147483647}Yes
reconstructedStrict local schema; not the private product API · Source and evidence

Plan

Plan schema fields
FieldType / limitsRequired
id{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"}Yes
name{"type":"string","minLength":1,"maxLength":100}Yes
description{"type":"string","minLength":1,"maxLength":400}Yes
audience{"type":"string","enum":["individual","team","enterprise"]}Yes
pricingMode{"type":"string","enum":["free","fixed","contact"]}Yes
currency{"const":"USD"}Yes
monthlyUsdCents{"anyOf":[{"type":"integer","minimum":0,"maximum":100000000},{"type":"null"}]}Yes
annualMonthlyUsdCents{"anyOf":[{"type":"integer","minimum":0,"maximum":100000000},{"type":"null"}]}Yes
featureIds{"type":"array","items":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},"minItems":0,"maxItems":50,"uniqueItems":true}Yes
ctaLabel{"type":"string","minLength":1,"maxLength":80}Yes
ctaHref{"anyOf":[{"$ref":"#/$defs/OfficialPublicHref"},{"type":"null"}]}Yes
updatedAt{"type":"string","minLength":20,"maxLength":30,"format":"date-time","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"}Yes
revision{"type":"integer","minimum":1}Yes
reconstructedStrict local schema; not the private product API · Source and evidence

Article

Article schema fields
FieldType / limitsRequired
id{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"}Yes
slug{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"}Yes
kind{"type":"string","enum":["article","resource","changelog"]}Yes
title{"type":"string","minLength":1,"maxLength":240}Yes
summary{"anyOf":[{"type":"string","minLength":1,"maxLength":600},{"type":"null"}]}Yes
author{"anyOf":[{"$ref":"#/$defs/Person"},{"type":"null"}]}Yes
publishedAt{"anyOf":[{"type":"string","minLength":20,"maxLength":30,"format":"date-time","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"},{"type":"null"}]}Yes
updatedAt{"type":"string","minLength":20,"maxLength":30,"format":"date-time","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"}Yes
category{"type":"string","enum":["guide","engineering","news","release"]}Yes
locale{"type":"string","minLength":2,"maxLength":20,"pattern":"^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"}Yes
coverAssetId{"anyOf":[{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},{"type":"null"}]}Yes
publicUrl{"$ref":"#/$defs/OfficialPublicHref"}Yes
blocks{"type":"array","items":{"$ref":"#/$defs/ArticleBlock"},"minItems":1,"maxItems":80}Yes
revision{"type":"integer","minimum":1}Yes
reconstructedStrict local schema; not the private product API · Source and evidence

Feature

Feature schema fields
FieldType / limitsRequired
id{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"}Yes
title{"type":"string","minLength":1,"maxLength":160}Yes
summary{"type":"string","minLength":1,"maxLength":600}Yes
platforms{"type":"array","items":{"type":"string","enum":["macos","windows","ios","browser"]},"minItems":1,"maxItems":4,"uniqueItems":true}Yes
entitlementLabel{"type":"string","enum":["free","pro","teams","unverified"]}Yes
availabilityLabel{"type":"string","minLength":1,"maxLength":100}Yes
mediaAssetId{"anyOf":[{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},{"type":"null"}]}Yes
publicUrl{"$ref":"#/$defs/OfficialPublicHref"}Yes
relatedFeatureIds{"type":"array","items":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"},"minItems":0,"maxItems":12,"uniqueItems":true}Yes
updatedAt{"type":"string","minLength":20,"maxLength":30,"format":"date-time","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"}Yes
revision{"type":"integer","minimum":1}Yes
reconstructedStrict local schema; not the private product API · Source and evidence

PublicFeedback

PublicFeedback schema fields
FieldType / limitsRequired
id{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"}Yes
category{"type":"string","enum":["feature-request","bug-report","billing-issue","ios","other"]}Yes
senderEmail{"type":"string","minLength":3,"maxLength":254,"format":"email","pattern":"^[^\\s@]+@example\\.com$"}Yes
appVersion{"anyOf":[{"type":"string","minLength":1,"maxLength":40},{"type":"null"}]}Yes
message{"type":"string","minLength":1,"maxLength":4000}Yes
attachments{"type":"array","items":{"$ref":"#/$defs/Attachment"},"minItems":0,"maxItems":5}Yes
submissionState{"type":"string","enum":["draft","validating","success","error","offline"]}Yes
createdAt{"type":"string","minLength":20,"maxLength":30,"format":"date-time","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"}Yes
bugType{"anyOf":[{"type":"string","enum":["not_working","crashing","freezing"]},{"type":"null"}]}Yes
feature{"anyOf":[{"type":"string","enum":["AI","Applications","Auto Quit","Calculator","Calendar/My Schedule","Clipboard History","Cloud Sync","Custom Themes","Deeplinks","Dictation","Extensions","Flight Tracker","Focus","Hyper Key","Notes","Quicklinks","Script Commands","Search Files","Settings","Snippets","Store","Window Management","Other"]},{"type":"null"}]}Yes
reconstructedStrict local schema; not the private product API · Source and evidence

Asset

Asset schema fields
FieldType / limitsRequired
id{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"}Yes
kind{"type":"string","enum":["icon","logo","font","screenshot","photo","illustration","video"]}Yes
mimeType{"type":"string","enum":["image/svg+xml","image/png","image/jpeg","image/webp","image/avif","font/woff2","video/mp4","video/webm"]}Yes
localPath{"type":"string","minLength":1,"maxLength":240,"pattern":"^assets/(?:[a-zA-Z0-9_-]+/)*[a-zA-Z0-9_-]+\\.(?:svg|png|jpg|jpeg|webp|avif|woff2|mp4|webm)$"}Yes
sourceUrl{"type":"string","minLength":8,"maxLength":600,"format":"uri","pattern":"^https://[^\\s]+$"}Yes
widthPx{"anyOf":[{"type":"integer","minimum":1,"maximum":20000},{"type":"null"}]}Yes
heightPx{"anyOf":[{"type":"integer","minimum":1,"maximum":20000},{"type":"null"}]}Yes
byteLength{"type":"integer","minimum":1,"maximum":104857600}Yes
sha256{"type":"string","minLength":64,"maxLength":64,"pattern":"^[a-f0-9]{64}$"}Yes
alt{"type":"string","minLength":0,"maxLength":400}Yes
decorative{"type":"boolean"}Yes
theme{"type":"string","enum":["dark","light","any"]}Yes
loading{"type":"string","enum":["eager","lazy"]}Yes
rights{"type":"object","additionalProperties":false,"properties":{"status":{"type":"string","enum":["package-license","open-font-license","private-reference-only","original"]},"notice":{"type":"string","minLength":1,"maxLength":600},"distribution":{"type":"string","enum":["private-reference-only","license-conditions","original"]}},"required":["status","notice","distribution"]}Yes
reconstructedStrict local schema; not the private product API · Source and evidence

CollectionEnvelope

CollectionEnvelope schema fields
FieldType / limitsRequired
schemaVersion{"const":1}Yes
requestId{"type":"integer","minimum":1}Yes
state{"type":"string","enum":["loading","ready","empty","partial","stale","error","offline","permission"]}Yes
items{"type":"array","items":{"$ref":"#/$defs/Extension"},"minItems":0,"maxItems":500}Yes
receivedAt{"anyOf":[{"type":"string","minLength":20,"maxLength":30,"format":"date-time","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"},{"type":"null"}]}Yes
expiresAt{"anyOf":[{"type":"string","minLength":20,"maxLength":30,"format":"date-time","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$"},{"type":"null"}]}Yes
hasMore{"const":false}Yes
message{"anyOf":[{"type":"string","minLength":1,"maxLength":400},{"type":"null"}]}Yes
reconstructedStrict local schema; not the private product API · Source and evidence

State and relationship ownership

OwnerOwnsDoes not own
CatalogQuery, category, result count, selected item, loading/error/status.Record content or global navigation.
ExtensionName, summary, publisher, commands, platforms, source URL.Installation entitlement or native command execution.
PlanCaptured price, currency, cadence, audience, tier and entitlement labels.Live billing API, taxes or customer eligibility.
Form draftCategory, email, message, selected local files and validation.Persistent account data or remote delivery.
DialogOpen state and focus-return target.Browser history except explicit detail navigation.
PublicationStatic version, local search index and proof links.Telemetry, visitor cookies or user accounts.

Use the fixtures

Valid, long, missing, mixed-script and malformed records exercise the contracts. The fixture file also enumerates the nine collection states and expected validation failures. IDs are stable strings; money uses integer minor units; dates use ISO8601 UTC; missing values use null rather than a misleading zero.

Run data validation · Shell
node designs/raycast/evidence/verification/data-contract-tests.mjs
Download fixtures
Download exact schemas
Loading index…↑ ↓ navigate · ↵ open

About this specimen

This is a local reconstruction of a public Raycast pattern. It demonstrates the interface contract; real accounts, installs and payments remain on the official product.

Open implementation

Icon contract