Meshtastic-Android/schemas/event_firmware.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://meshtastic.org/schemas/event_firmware.schema.json",
  "title": "Event Firmware Metadata",
  "description": "Offline-first display metadata for event-specific firmware editions. The bundled androidApp/src/main/assets/event_firmware.json shares the {version, generatedAt, source, <payload>[]} envelope used by device_links.json so a future Meshtastic API (planned GET /resource/eventFirmware) can reuse the same shape. Each record identifies its edition by the FirmwareEdition proto enum name in the `edition` field. This schema is the authoring contract for the bundled file and is bumped as the shape evolves; the runtime JSON parser is independently tolerant of unknown fields.",
  "type": "object",
  "required": ["version", "editions"],
  "additionalProperties": false,
  "properties": {
    "version": {
      "type": "integer",
      "minimum": 1,
      "description": "Schema/envelope version. Bump when the structure changes incompatibly."
    },
    "generatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "ISO-8601 timestamp the snapshot was generated."
    },
    "source": {
      "type": "string",
      "description": "Origin of this snapshot, e.g. \"bundled\" or the API URL it was frozen from."
    },
    "editions": {
      "type": "array",
      "description": "One record per event firmware edition.",
      "items": { "$ref": "#/$defs/edition" }
    }
  },
  "$defs": {
    "edition": {
      "type": "object",
      "required": ["edition", "displayName", "welcomeMessage"],
      "additionalProperties": false,
      "properties": {
        "edition": {
          "type": "string",
          "pattern": "^[A-Z0-9_]+$",
          "description": "FirmwareEdition proto enum name, e.g. \"HAMVENTION\". A pattern (not a fixed enum list) so adding a new event needs no schema change."
        },
        "displayName": {
          "type": "string",
          "description": "Human-readable name shown in the UI, e.g. \"Hamvention\" (vs the enum name \"HAMVENTION\")."
        },
        "welcomeMessage": {
          "type": "string",
          "description": "Plain (English) welcome string. NOTE: this is intentionally NOT localized — moving it into this data file drops the Crowdin per-language translation the app's string resources previously provided. Revisit when an upstream API / localization strategy is added."
        },
        "eventStart": {
          "type": ["string", "null"],
          "format": "date",
          "description": "ISO-8601 date (YYYY-MM-DD) the event begins, interpreted in timeZone. Seed values are best-effort and change yearly; the upstream sync is expected to own them."
        },
        "eventEnd": {
          "type": ["string", "null"],
          "format": "date",
          "description": "ISO-8601 date (YYYY-MM-DD) the event ends, interpreted in timeZone."
        },
        "timeZone": {
          "type": ["string", "null"],
          "description": "IANA time zone id (e.g. \"America/New_York\") so eventStart/eventEnd resolve in the event's local time, not the device's."
        },
        "location": {
          "type": ["string", "null"],
          "description": "Free-text venue/city for display, e.g. \"Las Vegas, Nevada, USA\"."
        },
        "iconUrl": {
          "type": ["string", "null"],
          "format": "uri",
          "description": "URL of the event branding icon. Null when no hosted icon exists yet."
        },
        "accentColor": {
          "type": ["string", "null"],
          "pattern": "^#[0-9A-Fa-f]{6}$",
          "description": "Brand/accent color (#RRGGBB) for ambient event theming."
        },
        "links": {
          "type": "array",
          "description": "Labeled links for the event (website, schedule, map, …).",
          "items": { "$ref": "#/$defs/link" }
        }
      }
    },
    "link": {
      "type": "object",
      "required": ["label", "url"],
      "additionalProperties": false,
      "properties": {
        "label": { "type": "string", "description": "Display text for the link." },
        "url": { "type": "string", "format": "uri", "description": "Destination URL." }
      }
    }
  }
}