@bridgething/catalog 0.1.0

package/schema.v1.json

@@ -0,0 +1,236 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://apps.bridgething.com/schemas/catalog/v1.json",
+  "title": "bridgething App Catalog",
+  "description": "A federated catalog of installable webapps for a bridgething-flashed Spotify Car Thing. Served at any source URL; the companion aggregates entries across subscribed sources.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "updated_at", "repo", "apps", "recommended_sources"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri",
+      "description": "Optional pointer to this schema. Editors auto-validate when present."
+    },
+    "schema": {
+      "type": "string",
+      "const": "catalog.v1",
+      "description": "Schema discriminant. Consumers MUST refuse a catalog whose schema they do not implement."
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 UTC timestamp of when this catalog was last regenerated."
+    },
+    "repo": {
+      "$ref": "#/$defs/Repo"
+    },
+    "apps": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/AppEntry"
+      },
+      "description": "Installable webapps offered by this source."
+    },
+    "recommended_sources": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/RecommendedSource"
+      },
+      "description": "Other catalog sources this source suggests adding. Empty on most sources; the official catalog populates it as a quick-add list plus the attestation lever."
+    }
+  },
+  "$defs": {
+    "Uuid": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Stable webapp identity. Drives upgrade-in-place and the KV namespace on the device, so it MUST NOT change across versions."
+    },
+    "Version": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9](?:[A-Za-z0-9.+\\-]*[A-Za-z0-9])?$",
+      "minLength": 1,
+      "maxLength": 100,
+      "description": "Opaque webapp version identifier. Semver is recommended but not enforced."
+    },
+    "Semver": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:[.+\\-][0-9A-Za-z.\\-]+)?$",
+      "description": "Dotted semver, no leading 'v'. The device's libbridgething_version is reported v-prefixed on the wire; the companion strips the prefix before comparing."
+    },
+    "Sha256": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$",
+      "description": "Lowercase hex SHA-256 digest of the artifact bytes. Integrity, not authenticity."
+    },
+    "Repo": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "description", "homepage", "icon"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "description": "Display name of this catalog source."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 300
+        },
+        "homepage": {
+          "type": ["string", "null"],
+          "format": "uri"
+        },
+        "icon": {
+          "type": ["string", "null"],
+          "format": "uri",
+          "description": "Square source icon for the companion's source list."
+        }
+      }
+    },
+    "AppEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name", "description", "author", "icon", "homepage", "source", "versions"],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/Uuid"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "description": "Display name."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 300,
+          "description": "One-line tagline for store cards."
+        },
+        "author": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "icon": {
+          "type": ["string", "null"],
+          "format": "uri",
+          "description": "Hosted square icon. The publish step extracts the bundle's icon and uploads it; null until then."
+        },
+        "homepage": {
+          "type": ["string", "null"],
+          "format": "uri"
+        },
+        "source": {
+          "type": ["string", "null"],
+          "format": "uri",
+          "description": "Repository or source URL, for users who want to check it themselves."
+        },
+        "versions": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/AppVersion"
+          },
+          "description": "Published versions, newest-first. The companion installs the newest version compatible with the connected device."
+        }
+      }
+    },
+    "AppVersion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "version",
+        "released_at",
+        "download",
+        "permissions",
+        "min_libbridgething_version",
+        "changelog"
+      ],
+      "properties": {
+        "version": {
+          "$ref": "#/$defs/Version"
+        },
+        "released_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "download": {
+          "$ref": "#/$defs/Download"
+        },
+        "permissions": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true,
+          "description": "Permission catalog keys this version requests (net.fetch, geo, ...). Shown at install, informational, never a gate."
+        },
+        "role": {
+          "enum": ["standard", "launcher"],
+          "description": "Mirrors the bundle manifest's role. A launcher can take the device's launcher slot and replace the built-in hub. Absent means standard."
+        },
+        "provides_overlay": {
+          "type": "boolean",
+          "description": "Whether this version ships an overlay the device can inject over every webapp. Absent means it does not."
+        },
+        "min_libbridgething_version": {
+          "$ref": "#/$defs/Semver"
+        },
+        "changelog": {
+          "type": ["string", "null"],
+          "description": "Markdown changelog for this version."
+        }
+      }
+    },
+    "Download": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["url", "size", "sha256"],
+      "properties": {
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Direct download URL for the webapp zip."
+        },
+        "size": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Size of the artifact in bytes."
+        },
+        "sha256": {
+          "$ref": "#/$defs/Sha256"
+        }
+      }
+    },
+    "RecommendedSource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "url", "description", "attested"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "A catalog.v1 manifest URL the companion can subscribe to."
+        },
+        "description": {
+          "type": ["string", "null"],
+          "maxLength": 300
+        },
+        "attested": {
+          "type": "boolean",
+          "description": "True if the publishing source vouches for this URL. Editorial signal, not a trust boundary."
+        }
+      }
+    }
+  }
+}