ObjectStackObjectStack

Marketplace

Marketplace protocol schemas

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 plugin locally using ObjectStack CLI

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

3. Build     → Run `os plugin build` (bundle + sign)

4. Submit    → Run `os plugin publish` (submit to marketplace)

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

Source: packages/spec/src/cloud/marketplace.zod.ts

TypeScript Usage

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

PropertyTypeRequiredDescription
downloadUrlstring✅Artifact download URL (may be pre-signed)
sha256string✅SHA256 checksum for verification
sizeinteger✅Artifact size in bytes
formatEnum<'tgz' | 'zip'>✅Artifact format
expiresAtstringoptionalURL expiration timestamp for pre-signed URLs

ArtifactReference

Reference to a downloadable package artifact

Properties

PropertyTypeRequiredDescription
urlstring✅Artifact download URL
sha256string✅SHA256 checksum
sizeinteger✅Artifact size in bytes
formatEnum<'tgz' | 'zip'>✅Artifact format
uploadedAtstring✅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

PropertyTypeRequiredDescription
listingIdstring✅Marketplace listing ID
versionstringoptionalVersion to install
licenseKeystringoptionalLicense key for paid packages
settingsRecord<string, any>optionalUser-provided settings at install time
enableOnInstallboolean✅Whether to enable immediately after install
artifactRefObjectoptionalArtifact reference for direct installation
tenantIdstringoptionalTenant identifier

MarketplaceInstallResponse

Install from marketplace response

Properties

PropertyTypeRequiredDescription
successboolean✅Whether installation succeeded
packageIdstringoptionalInstalled package identifier
versionstringoptionalInstalled version
messagestringoptionalInstallation status message

MarketplaceListing

Public-facing package listing on the marketplace

Properties

PropertyTypeRequiredDescription
idstring✅Listing ID (matches package manifest ID)
packageIdstring✅Package identifier
publisherIdstring✅Publisher ID
statusEnum<'draft' | 'submitted' | 'in-review' | 'approved' | 'published' | 'rejected' | 'suspended' | 'deprecated' | 'unlisted'>✅Publication state: draft, published, under-review, suspended, deprecated, or unlisted
namestring✅Display name
taglinestringoptionalShort tagline (max 120 chars)
descriptionstringoptionalFull description (Markdown)
categoryEnum<'crm' | 'erp' | 'hr' | 'finance' | 'project' | 'collaboration' | 'analytics' | 'integration' | 'automation' | 'ai' | 'security' | 'developer-tools' | 'ui-theme' | 'storage' | 'other'>✅Package category
tagsstring[]optionalSearch tags
iconUrlstringoptionalPackage icon URL
screenshotsObject[]optionalScreenshots
documentationUrlstringoptionalDocumentation URL
supportUrlstringoptionalSupport URL
repositoryUrlstringoptionalSource repository URL
pricingEnum<'free' | 'freemium' | 'paid' | 'subscription' | 'usage-based' | 'contact-sales'>✅Pricing model
priceInCentsintegeroptionalPrice in cents (e.g. 999 = $9.99)
latestVersionstring✅Latest published version
minPlatformVersionstringoptionalMinimum ObjectStack platform version
versionsObject[]optionalPublished versions
statsObjectoptionalAggregate marketplace statistics
publishedAtstringoptionalFirst published timestamp
updatedAtstringoptionalLast updated timestamp

MarketplaceSearchRequest

Marketplace search request

Properties

PropertyTypeRequiredDescription
querystringoptionalFull-text search query
categoryEnum<'crm' | 'erp' | 'hr' | 'finance' | 'project' | 'collaboration' | 'analytics' | 'integration' | 'automation' | 'ai' | 'security' | 'developer-tools' | 'ui-theme' | 'storage' | 'other'>optionalFilter by category
tagsstring[]optionalFilter by tags
pricingEnum<'free' | 'freemium' | 'paid' | 'subscription' | 'usage-based' | 'contact-sales'>optionalFilter by pricing model
publisherVerificationEnum<'unverified' | 'pending' | 'verified' | 'trusted' | 'partner'>optionalFilter by publisher verification level
sortByEnum<'relevance' | 'popularity' | 'rating' | 'newest' | 'updated' | 'name'>✅Sort field
sortDirectionEnum<'asc' | 'desc'>✅Sort direction
pageinteger✅Page number
pageSizeinteger✅Items per page
platformVersionstringoptionalFilter by platform version compatibility

MarketplaceSearchResponse

Marketplace search response

Properties

PropertyTypeRequiredDescription
itemsObject[]✅Search result listings
totalinteger✅Total matching results
pageinteger✅Current page number
pageSizeinteger✅Items per page
facetsObjectoptionalAggregation facets for refining search

PackageSubmission

Developer submission of a package version for review

Properties

PropertyTypeRequiredDescription
idstring✅Submission ID
packageIdstring✅Package identifier
versionstring✅Version being submitted
publisherIdstring✅Publisher submitting
statusEnum<'pending' | 'scanning' | 'in-review' | 'changes-requested' | 'approved' | 'rejected'>✅Review status
artifactUrlstring✅Package artifact URL for review
releaseNotesstringoptionalRelease notes for this version
isNewListingboolean✅Whether this is a new listing submission
scanResultsObjectoptionalAutomated scan results
reviewerNotesstringoptionalNotes from the platform reviewer
submittedAtstringoptionalSubmission timestamp
reviewedAtstringoptionalReview completion timestamp

PricingModel

Package pricing model

Allowed Values

  • free
  • freemium
  • paid
  • subscription
  • usage-based
  • contact-sales

Publisher

Developer or organization that publishes packages

Properties

PropertyTypeRequiredDescription
idstring✅Publisher ID
namestring✅Publisher display name
typeEnum<'individual' | 'organization'>✅Publisher type
verificationEnum<'unverified' | 'pending' | 'verified' | 'trusted' | 'partner'>✅Publisher verification status
emailstringoptionalContact email
websitestringoptionalPublisher website
logoUrlstringoptionalPublisher logo URL
descriptionstringoptionalPublisher description
registeredAtstringoptionalPublisher registration timestamp

PublisherVerification

Publisher verification status

Allowed Values

  • unverified
  • pending
  • verified
  • trusted
  • partner

On this page

Marketplace ProtocolArchitecture AlignmentDeveloper Publishing FlowPlatform Management FlowTypeScript UsageArtifactDownloadResponsePropertiesArtifactReferencePropertiesListingStatusAllowed ValuesMarketplaceCategoryAllowed ValuesMarketplaceInstallRequestPropertiesMarketplaceInstallResponsePropertiesMarketplaceListingPropertiesMarketplaceSearchRequestPropertiesMarketplaceSearchResponsePropertiesPackageSubmissionPropertiesPricingModelAllowed ValuesPublisherPropertiesPublisherVerificationAllowed Values