---
title: Marketplace
description: Marketplace protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

# Marketplace Protocol

Defines the core schemas for the plugin marketplace ecosystem, covering:

- **Developer Side**: Package publishing, submission, and version releases

- **Platform Side**: Marketplace listing, review, approval, and discovery

This protocol defines the contract between plugin developers, the marketplace

platform, and customers who install plugins.

## Architecture Alignment

- **Salesforce AppExchange**: Security review, managed packages, listing profiles

- **VS Code Marketplace**: Extension publishing, ratings, verified publishers

- **npm Registry**: Package publishing, versioning, scoped packages

- **Shopify App Store**: App review process, billing integration, merchant installs

## Developer Publishing Flow

```

1. Develop   → Build the project locally using ObjectStack CLI

2. Validate  → Run `os validate` (schema + security checks)

3. Build     → Run `os build` (compile to dist/objectstack.json)

4. Submit    → Run `os projects bind <id> --artifact dist/objectstack.json`

5. Review    → Platform conducts automated + manual review

6. Publish   → Approved listing goes live on marketplace

```

## Platform Management Flow

```

1. Receive   → Accept submissions from verified publishers

2. Scan      → Automated security scan and compatibility check

3. Review    → Human review for quality and policy compliance

4. Catalog   → Index in marketplace search catalog

5. Monitor   → Track installs, ratings, issues, and enforce SLAs

```

<Callout type="info">
**Source:** `packages/spec/src/cloud/marketplace.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { ArtifactDownloadResponse, ArtifactReference, ListingStatus, MarketplaceCategory, MarketplaceInstallRequest, MarketplaceInstallResponse, MarketplaceListing, MarketplaceSearchRequest, MarketplaceSearchResponse, PackageSubmission, PricingModel, Publisher, PublisherVerification } from '@objectstack/spec/cloud';
import type { ArtifactDownloadResponse, ArtifactReference, ListingStatus, MarketplaceCategory, MarketplaceInstallRequest, MarketplaceInstallResponse, MarketplaceListing, MarketplaceSearchRequest, MarketplaceSearchResponse, PackageSubmission, PricingModel, Publisher, PublisherVerification } from '@objectstack/spec/cloud';

// Validate data
const result = ArtifactDownloadResponse.parse(data);
```

---

## ArtifactDownloadResponse

Artifact download response with integrity metadata

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **downloadUrl** | `string` | ✅ | Artifact download URL (may be pre-signed) |
| **sha256** | `string` | ✅ | SHA256 checksum for verification |
| **size** | `integer` | ✅ | Artifact size in bytes |
| **format** | `Enum<'tgz' \| 'zip'>` | ✅ | Artifact format |
| **expiresAt** | `string` | optional | URL expiration timestamp for pre-signed URLs |


---

## ArtifactReference

Reference to a downloadable package artifact

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **url** | `string` | ✅ | Artifact download URL |
| **sha256** | `string` | ✅ | SHA256 checksum |
| **size** | `integer` | ✅ | Artifact size in bytes |
| **format** | `Enum<'tgz' \| 'zip'>` | ✅ | Artifact format |
| **uploadedAt** | `string` | ✅ | Upload timestamp |


---

## ListingStatus

Marketplace listing status

### Allowed Values

* `draft`
* `submitted`
* `in-review`
* `approved`
* `published`
* `rejected`
* `suspended`
* `deprecated`
* `unlisted`


---

## MarketplaceCategory

Marketplace package category

### Allowed Values

* `crm`
* `erp`
* `hr`
* `finance`
* `project`
* `collaboration`
* `analytics`
* `integration`
* `automation`
* `ai`
* `security`
* `developer-tools`
* `ui-theme`
* `storage`
* `other`


---

## MarketplaceInstallRequest

Install from marketplace request

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **listingId** | `string` | ✅ | Marketplace listing ID |
| **version** | `string` | optional | Version to install |
| **licenseKey** | `string` | optional | License key for paid packages |
| **settings** | `Record<string, any>` | optional | User-provided settings at install time |
| **enableOnInstall** | `boolean` | ✅ | Whether to enable immediately after install |
| **artifactRef** | `Object` | optional | Artifact reference for direct installation |
| **tenantId** | `string` | optional | Tenant identifier |


---

## MarketplaceInstallResponse

Install from marketplace response

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Whether installation succeeded |
| **packageId** | `string` | optional | Installed package identifier |
| **version** | `string` | optional | Installed version |
| **message** | `string` | optional | Installation status message |


---

## MarketplaceListing

Public-facing package listing on the marketplace

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Listing ID (matches package manifest ID) |
| **packageId** | `string` | ✅ | Package identifier |
| **packageType** | `Enum<'app'>` | ✅ | Consumer-installable package type (ADR-0019: only `app` is listable) |
| **publisherId** | `string` | ✅ | Publisher ID |
| **status** | `Enum<'draft' \| 'submitted' \| 'in-review' \| 'approved' \| 'published' \| 'rejected' \| 'suspended' \| 'deprecated' \| 'unlisted'>` | ✅ | Publication state: draft, published, under-review, suspended, deprecated, or unlisted |
| **name** | `string` | ✅ | Display name |
| **tagline** | `string` | optional | Short tagline (max 120 chars) |
| **description** | `string` | optional | Full description (Markdown) |
| **category** | `Enum<'crm' \| 'erp' \| 'hr' \| 'finance' \| 'project' \| 'collaboration' \| 'analytics' \| 'integration' \| 'automation' \| 'ai' \| 'security' \| 'developer-tools' \| 'ui-theme' \| 'storage' \| 'other'>` | ✅ | Package category |
| **tags** | `string[]` | optional | Search tags |
| **iconUrl** | `string` | optional | Package icon URL |
| **screenshots** | `Object[]` | optional | Screenshots |
| **documentationUrl** | `string` | optional | Documentation URL |
| **supportUrl** | `string` | optional | Support URL |
| **repositoryUrl** | `string` | optional | Source repository URL |
| **pricing** | `Enum<'free' \| 'freemium' \| 'paid' \| 'subscription' \| 'usage-based' \| 'contact-sales'>` | ✅ | Pricing model |
| **priceInCents** | `integer` | optional | Price in cents (e.g. 999 = $9.99) |
| **latestVersion** | `string` | ✅ | Latest published version |
| **minPlatformVersion** | `string` | optional | Minimum ObjectStack platform version |
| **versions** | `Object[]` | optional | Published versions |
| **stats** | `Object` | optional | Aggregate marketplace statistics |
| **publishedAt** | `string` | optional | First published timestamp |
| **updatedAt** | `string` | optional | Last updated timestamp |
| **translations** | `Record<string, Object>` | optional | Locale-keyed overrides for name / tagline / description / screenshot captions |


---

## MarketplaceSearchRequest

Marketplace search request

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **query** | `string` | optional | Full-text search query |
| **category** | `Enum<'crm' \| 'erp' \| 'hr' \| 'finance' \| 'project' \| 'collaboration' \| 'analytics' \| 'integration' \| 'automation' \| 'ai' \| 'security' \| 'developer-tools' \| 'ui-theme' \| 'storage' \| 'other'>` | optional | Filter by category |
| **tags** | `string[]` | optional | Filter by tags |
| **pricing** | `Enum<'free' \| 'freemium' \| 'paid' \| 'subscription' \| 'usage-based' \| 'contact-sales'>` | optional | Filter by pricing model |
| **publisherVerification** | `Enum<'unverified' \| 'pending' \| 'verified' \| 'trusted' \| 'partner'>` | optional | Filter by publisher verification level |
| **sortBy** | `Enum<'relevance' \| 'popularity' \| 'rating' \| 'newest' \| 'updated' \| 'name'>` | ✅ | Sort field |
| **sortDirection** | `Enum<'asc' \| 'desc'>` | ✅ | Sort direction |
| **page** | `integer` | ✅ | Page number |
| **pageSize** | `integer` | ✅ | Items per page |
| **platformVersion** | `string` | optional | Filter by platform version compatibility |


---

## MarketplaceSearchResponse

Marketplace search response

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **items** | `Object[]` | ✅ | Search result listings |
| **total** | `integer` | ✅ | Total matching results |
| **page** | `integer` | ✅ | Current page number |
| **pageSize** | `integer` | ✅ | Items per page |
| **facets** | `Object` | optional | Aggregation facets for refining search |


---

## PackageSubmission

Developer submission of a package version for review

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Submission ID |
| **packageId** | `string` | ✅ | Package identifier |
| **version** | `string` | ✅ | Version being submitted |
| **publisherId** | `string` | ✅ | Publisher submitting |
| **status** | `Enum<'pending' \| 'scanning' \| 'in-review' \| 'changes-requested' \| 'approved' \| 'rejected'>` | ✅ | Review status |
| **artifactUrl** | `string` | ✅ | Package artifact URL for review |
| **releaseNotes** | `string` | optional | Release notes for this version |
| **isNewListing** | `boolean` | ✅ | Whether this is a new listing submission |
| **scanResults** | `Object` | optional | Automated scan results |
| **reviewerNotes** | `string` | optional | Notes from the platform reviewer |
| **submittedAt** | `string` | optional | Submission timestamp |
| **reviewedAt** | `string` | optional | Review completion timestamp |


---

## PricingModel

Package pricing model

### Allowed Values

* `free`
* `freemium`
* `paid`
* `subscription`
* `usage-based`
* `contact-sales`


---

## Publisher

Developer or organization that publishes packages

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Publisher ID |
| **name** | `string` | ✅ | Publisher display name |
| **type** | `Enum<'individual' \| 'organization'>` | ✅ | Publisher type |
| **verification** | `Enum<'unverified' \| 'pending' \| 'verified' \| 'trusted' \| 'partner'>` | ✅ | Publisher verification status |
| **email** | `string` | optional | Contact email |
| **website** | `string` | optional | Publisher website |
| **logoUrl** | `string` | optional | Publisher logo URL |
| **description** | `string` | optional | Publisher description |
| **registeredAt** | `string` | optional | Publisher registration timestamp |


---

## PublisherVerification

Publisher verification status

### Allowed Values

* `unverified`
* `pending`
* `verified`
* `trusted`
* `partner`


---

