#Manifest JSON Schemas

The package exports config-schema.json as @theaiplatform/miniapp-sdk/config-schema.json. Assign that path to $schema in the generated tap-miniapp.build.json for editor completion and validation that follows the installed SDK version.

{
  "$schema": "./node_modules/@theaiplatform/miniapp-sdk/config-schema.json",
  "buildSchemaVersion": 2
}

The build schema covers presentation, compatibility, target graphs, contributions, permissions, package events, and lifecycle policy. Unknown fields fail where the format closes an object, which catches misspellings before publication.

#Declare a Context Action

An action.command contribution adds a host-native action to one or more artifact contexts. The host launches the exact declared package surface and delivers an immutable artifact reference. It does not execute package code directly from the menu or copy the artifact into the launch message.

The following compiled contributions array declares one desktop action and its target surface. Emit this structure from the typed authoring definition or a contribution provider. Do not hand-edit the generated build manifest.

[
  {
    "kind": "ui.surface",
    "id": "artifact-inspector",
    "apiVersion": 1,
    "targets": {
      "desktop": {
        "expose": "./ui/artifact-inspector",
        "runtime": "webview"
      }
    },
    "authorization": {
      "onDemand": ["artifacts.read"]
    },
    "options": {
      "placement": "route",
      "scope": "workspace",
      "instancePolicy": "per-workspace"
    }
  },
  {
    "kind": "action.command",
    "id": "inspect-artifact",
    "apiVersion": 1,
    "targets": {
      "desktop": { "runtime": "host-declarative" }
    },
    "authorization": {
      "allOf": ["artifacts.read"]
    },
    "lifecycleScope": "installation",
    "options": {
      "label": "Inspect artifact",
      "description": "Open the selected artifact.",
      "contexts": [
        "channel-message",
        "pull-request",
        "task",
        "repository-issue"
      ],
      "launch": {
        "kind": "ui.surface",
        "contributionId": "artifact-inspector"
      }
    }
  },
  {
    "kind": "permission.catalog",
    "id": "permissions",
    "apiVersion": 1,
    "options": {
      "actions": [
        {
          "id": "artifacts.read",
          "resource": "artifact",
          "scopes": ["workspace"],
          "directActors": ["human"],
          "delegatedActors": [],
          "autonomyCeiling": "listen",
          "consent": "none",
          "risk": "read"
        }
      ],
      "levels": [
        {
          "id": "artifact-reader",
          "actions": ["artifacts.read"],
          "assignableTo": ["human"]
        }
      ]
    }
  }
]

apiVersion must be 1, lifecycleScope must be installation, and contexts must contain at least one unique supported value: channel-message, pull-request, task, or repository-issue. The action must select exactly the desktop target with an expose-free host-declarative runtime. The launched contribution must be a same-package, workspace-scoped ui.surface with a desktop webview module, a host-launchable placement (workspace-left, route, settings, or standalone-window), and artifacts.read in authorization.allOf or authorization.onDemand.

Declare artifacts.read with the workspace permission scope. The host derives the grant lookup from the launched workspace surface instead of accepting a package-selected resource or channel scope. A channel-message context still launches that workspace surface and carries only the opaque message reference; it does not turn the surface or permission into channel scope.

Packages that declare action.command must set compatibility.tapSdk to exclude versions before 0.15.0 and compatibility.tapHost to exclude versions before 2.9.0.

Schema acceptance does not prove that the selected native host implements the invocation path. See Artifact context resolution for the current runtime boundary.

The action's own authorization.allOf must be exactly ["artifacts.read"]; additional or alternate action grants are rejected. Legacy command payloads, implicit launch targets, duplicate contexts, unsupported targets, and unknown option fields fail schema or semantic validation.

Handle the delivered reference through context.launches, then resolve its current snapshot through sdk.artifacts.resolve.

#Validate Both Forms

Validate the compiled build manifest before target compilation and validate the assembled source manifest again. config-schema.json covers the schema-v2 build manifest. source-manifest.schema.json covers the provider-neutral schema-v2 byte inventory accepted at the import boundary.

import buildSchema from '@theaiplatform/miniapp-sdk/config-schema.json' with { type: 'json' };
import sourceSchema from '@theaiplatform/miniapp-sdk/source-manifest.schema.json' with { type: 'json' };

Use a JSON Schema 2020-compatible validator. Run the SDK's semantic build and package verification as well, because cross-contribution launch, target, permission, artifact, and integrity rules are stricter than shape validation. Report validation paths and messages without including secrets or authentication material.

#Versioning

Reference both schemas from the installed package instead of copying them into your repository. Upgrade the SDK and schemas together, then validate and build every target before selecting an existing miniapp release for production.

Schema validation proves structural compatibility. It does not prove that a publisher owns an identifier, a host grants a permission, an emitted asset matches its integrity, or a release can activate.