Manifest Format Reference¶

This page explains the Toolkit Format — the portable, self-describing structure used for toolkit distribution and import/export workflows.

Overview¶

A toolkit is a provenance wrapper around a manifest:

• Provenance Wrapper: Metadata about the toolkit (name, slug, version, license)
• Manifest: The entity definitions (templates, next steps, action buttons, shortcuts)

Both the Partner Admin API and the App API import/export flows use this same wrapper structure. The distinction lies in governance (who owns the installed entities) and distribution channel (API-managed vs. file-based).

Toolkit Format Structure¶

{
  "name": "Robert's Rules Essentials",
  "slug": "roberts-rules-essentials",
  "version": "1.0.0",
  "license": "MIT",
  "license_url": "https://opensource.org/licenses/MIT",
  "manifest": {
    "schema_version": "1",
    "toolkit_prompt": "You are a parliamentary procedure assistant...",
    "templates": [...],
    "next_steps": [...],
    "action_buttons": [...],
    "shortcuts": [...]
  }
}

Provenance Fields (Root Level)¶

Manifest Fields¶

Workflow Role Mappings¶

Workflows often include review nodes assigned to semantic roles (e.g., "Secretary", "Chair", "Product Owner"). The default_role_mappings field on a workflow provides portable defaults for resolving these roles.

Structure¶

{
  "workflows": [
    {
      "spec": { ... },
      "default_role_mappings": {
        "Secretary": { "group": "meeting_editor" },
        "Chair": {
          "group": "meeting_owner",
          "fallback": { "group": "workspace_owner" }
        },
        "Finance": {
          "group": "workspace_admin",
          "optional": true
        }
      }
    }
  ]
}

Role Mapping Target¶

Each mapping value is a RoleMappingTarget object with one of two forms:

User Target — Assign to a specific user by email (portable across environments):

{ "email": "reviewer@example.com", "optional": false }

Group Target — Assign to a participant group:

{
  "group": "workspace_admin",
  "fallback": { "group": "meeting_owner" },
  "optional": false
}

Supported Groups¶

Note: Workspace-scoped groups resolve against the meeting's workspace (where the meeting was created or, for duplicates, where it was copied).

Fallback Chains¶

When a group resolves to an empty set (e.g., no workspace admins), the fallback property specifies the next target to try. Fallbacks can chain recursively:

{
  "group": "workspace_admin",
  "fallback": {
    "group": "meeting_owner",
    "fallback": { "email": "default-reviewer@example.com" }
  }
}

Resolution Behavior¶

Runtime Overrides¶

When a user manually starts a workflow, they can override the default mappings via the role assignment UI. The defaults pre-populate the assignment dialog, but any role can be reassigned to a different user or group before execution.

Entity Referencing¶

Entities within a manifest reference each other using $id and $ref:

{
  "next_steps": [
    {
      "spec": {
        "$id": "ns-meeting-summary",
        "name": "Meeting Summary",
        ...
      },
      "action_buttons": [
        { "action_button": { "$ref": "ab-email-summary" } }
      ]
    }
  ],
  "action_buttons": [
    {
      "spec": {
        "$id": "ab-email-summary",
        "name": "Email Summary",
        ...
      }
    }
  ]
}

• $id: Declares a manifest-local identifier for an entity
• $ref: References another entity by its $id

Upon installation, these local identifiers are resolved to database UUIDs. The installation response includes an entity map showing the $id → UUID mappings.

API Channels & Governance¶

The same toolkit format is used by two different API channels, with different governance outcomes:

Partner-Owned Toolkits¶

When a toolkit is created via the Partner Admin API:

• Entities are owned by the partner app (ownership_type: PARTNER)
• The partner can push updates via the versioning API
• Workspaces install/uninstall but cannot modify the entities
• Updates propagate to all installed workspaces

Workspace-Owned Toolkits¶

When a toolkit is imported via the App API:

• Entities are owned by the importing workspace (ownership_type: WORKSPACE)
• The workspace can edit entities directly
• No automatic updates from external sources
• Ideal for customization and local iteration

Slug Stability¶

The slug field serves as a stable identifier across imports and upgrades:

1. Deduplication: If you import a toolkit with the same slug, the system updates existing entities
2. Portability: Export a toolkit, share the file, import elsewhere — slugs maintain identity
3. Upgrade Detection: When a partner publishes a new version, the slug links to prior installations

Best practice: Use descriptive, hierarchical slugs like acme-sales-discovery or roberts-rules-essentials.

Schema Versioning¶

The schema_version field in the manifest enables forward compatibility:

{
  "manifest": {
    "schema_version": "1",
    ...
  }
}

• Current version: "1"
• Future versions may add new entity types or fields
• The API will reject manifests with unsupported schema versions
• Older manifests remain compatible as the schema evolves

Worked Examples¶

See the Robert's Rules toolkit examples for complete, production-ready toolkit files:

• roberts-rules-essentials.json — Simplified parliamentary procedure
• roberts-rules-standard.json — Full Robert's Rules implementation

These examples demonstrate all entity types, cross-references, and best practices.

Related Documentation¶

• Toolkit Overview — Introduction and quick start
• Icon Reference — Visual gallery of supported icons
• Ownership & Distribution — Governance models
• Entity Lifecycle — How entities flow through installation