Social Platform

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://openpresentation.org/schema/opf-social-platform/v1",
  "$comment": "The v1 in the $id is the pre-1.0 line, not a frozen contract: this schema may change in any 0.x minor release. The release that produced this copy is the version of the @openpresentation/opf package it came from (opf --version; opf schemas lists it next to each id). See docs/schema-versioning.md.",
  "title": "Social Platform",
  "description": "Schema for social-platform records: display metadata for authoring UIs (name, brand color, handle example) alongside the URL patterns. The keys of a Socials object are an engine vocabulary validated directly; engines link a handle with the patterns in spec/reference/engine-vocabularies.json and never look a social-platform record up. pptx.gallery publishes these records and @openpresentation/gallery ships them as catalogDisplay.socialPlatforms.",
  "type": "object",
  "required": [
    "$schema",
    "id",
    "name"
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "const": "https://openpresentation.org/schema/opf-social-platform/v1",
      "description": "Identifies this record as a social-platform entry in the openpresentation.org catalog."
    },
    "id": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "description": "The social platform's key, as written in a Socials object. Lowercase kebab-case.",
      "examples": [
        "linkedin",
        "x",
        "github",
        "youtube",
        "instagram",
        "facebook",
        "tiktok",
        "threads",
        "mastodon",
        "bluesky"
      ]
    },
    "name": {
      "type": "string",
      "description": "Human-readable platform name shown in pickers and footers.",
      "examples": [
        "LinkedIn",
        "X",
        "GitHub",
        "YouTube",
        "Instagram",
        "Facebook",
        "TikTok",
        "Threads",
        "Mastodon",
        "Bluesky"
      ]
    },
    "summary": {
      "type": "string",
      "description": "One-sentence positioning of the platform — what it's used for and who's on it.",
      "examples": [
        "Professional social network for individuals and companies.",
        "Real-time microblog for news, opinions, and discussion."
      ]
    },
    "description": {
      "type": "string",
      "description": "Longer prose describing the platform and any rendering conventions (e.g., handle prefixes, distributed instances).",
      "examples": [
        "LinkedIn distinguishes between member profiles ('/in/<handle>') and company pages ('/company/<handle>'). Renderers should pick the appropriate URL pattern based on whether the parent is an Organization or a Speaker."
      ]
    },
    "baseUrl": {
      "type": "string",
      "format": "uri",
      "description": "Canonical base URL of the platform — used as the prefix when normalizing handles to full URLs.",
      "examples": [
        "https://linkedin.com",
        "https://x.com",
        "https://github.com",
        "https://youtube.com"
      ]
    },
    "profileUrlPattern": {
      "type": "string",
      "description": "URL pattern for individual member profiles. Use '{handle}' as the placeholder for the handle (with the prefix already stripped).",
      "examples": [
        "https://linkedin.com/in/{handle}",
        "https://x.com/{handle}",
        "https://github.com/{handle}",
        "https://youtube.com/@{handle}"
      ]
    },
    "companyUrlPattern": {
      "type": "string",
      "description": "Optional URL pattern for organization / company pages, when the platform distinguishes them from member profiles. Use '{handle}' as the placeholder.",
      "examples": [
        "https://linkedin.com/company/{handle}",
        "https://github.com/{handle}",
        "https://facebook.com/{handle}"
      ]
    },
    "handlePrefix": {
      "type": "string",
      "description": "Conventional prefix character displayed before the handle (e.g. '@' for X / Mastodon / Threads / TikTok). Empty string when no prefix is used. Renderers strip it before substituting into URL patterns.",
      "examples": [
        "@",
        ""
      ]
    },
    "handleExample": {
      "type": "string",
      "description": "Example handle in its conventional rendered form, used by picker UIs and validation hints.",
      "examples": [
        "alice-chen",
        "@alicechen",
        "alicechen",
        "alice.bsky.social",
        "@alice@hachyderm.io"
      ]
    },
    "brandColor": {
      "type": "string",
      "description": "Brand color (hex) for branded icon chips, link styling, or section accents in authoring UIs. Catalog metadata: engines do not draw it.",
      "examples": [
        "#0A66C2",
        "#000000",
        "#181717",
        "#FF0000"
      ]
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Free-form labels for filtering and search.",
      "examples": [
        [
          "professional",
          "default"
        ],
        [
          "microblog",
          "news"
        ],
        [
          "developer",
          "code"
        ],
        [
          "video"
        ],
        [
          "decentralized"
        ]
      ]
    },
    "preview": {
      "type": "object",
      "description": "Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional; engines fall back gracefully when previews aren't available.",
      "properties": {
        "src": {
          "type": "string",
          "format": "uri",
          "description": "Main preview image (PNG/JPG)."
        },
        "thumbnailSrc": {
          "type": "string",
          "format": "uri",
          "description": "Smaller thumbnail preview suited to dense grid views."
        },
        "vectorSrc": {
          "type": "string",
          "format": "uri",
          "description": "SVG / vector preview for crisp scaling at any size."
        }
      }
    }
  }
}