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 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

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

TypeScript Usage

import { ArtifactDownloadResponseSchema, ArtifactReferenceSchema, ListingStatusSchema, MarketplaceCategorySchema, MarketplaceInstallRequestSchema, MarketplaceInstallResponseSchema, MarketplaceListingSchema, MarketplaceSearchRequestSchema, MarketplaceSearchResponseSchema, PackageSubmissionSchema, PricingModelSchema, PublisherSchema, PublisherVerificationSchema } 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 = ArtifactDownloadResponseSchema.parse(data);

ArtifactDownloadResponse

Artifact download response with integrity metadata

Properties

PropertyTypeRequiredDescription
downloadUrlstringArtifact download URL (may be pre-signed)
sha256stringSHA256 checksum for verification
sizeintegerArtifact size in bytes
formatEnum<'tgz' | 'zip'>Artifact format
expiresAtstringoptionalURL expiration timestamp for pre-signed URLs

ArtifactReference

Reference to a downloadable package artifact

Properties

PropertyTypeRequiredDescription
urlstringArtifact download URL
sha256stringSHA256 checksum
sizeintegerArtifact size in bytes
formatEnum<'tgz' | 'zip'>Artifact format
uploadedAtstringUpload 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
listingIdstringMarketplace listing ID
versionstringoptionalVersion to install
licenseKeystringoptionalLicense key for paid packages
settingsRecord<string, any>optionalUser-provided settings at install time
enableOnInstallbooleanWhether to enable immediately after install
artifactRef{ url: string; sha256: string; size: integer; format: Enum<'tgz' | 'zip'>; … }optionalArtifact reference for direct installation
tenantIdstringoptionalTenant identifier

MarketplaceInstallResponse

Install from marketplace response

Properties

PropertyTypeRequiredDescription
successbooleanWhether installation succeeded
packageIdstringoptionalInstalled package identifier
versionstringoptionalInstalled version
messagestringoptionalInstallation status message

MarketplaceListing

Public-facing package listing on the marketplace

Properties

PropertyTypeRequiredDescription
idstringListing ID (matches package manifest ID)
packageIdstringPackage identifier
packageTypeEnum<'app'>Consumer-installable package type (ADR-0019: only app is listable)
publisherIdstringPublisher ID
statusEnum<'draft' | 'submitted' | 'in-review' | 'approved' | 'published' | 'rejected' | 'suspended' | 'deprecated' | 'unlisted'>Publication state: draft, published, under-review, suspended, deprecated, or unlisted
namestringDisplay 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
screenshots{ url: string; caption?: string }[]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)
latestVersionstringLatest published version
minPlatformVersionstringoptionalMinimum ObjectStack platform version
versions{ version: string; releaseDate: string; releaseNotes?: string; minPlatformVersion?: string; … }[]optionalPublished versions
stats{ totalInstalls: integer; activeInstalls: integer; averageRating?: number; totalRatings: integer; … }optionalAggregate marketplace statistics
publishedAtstringoptionalFirst published timestamp
updatedAtstringoptionalLast updated timestamp
translationsRecord<string, { displayName?: string; description?: string; readme?: string; tagline?: string; … }>optionalLocale-keyed overrides for name / tagline / description / screenshot captions

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
pageintegerPage number
pageSizeintegerItems per page
platformVersionstringoptionalFilter by platform version compatibility

MarketplaceSearchResponse

Marketplace search response

Properties

PropertyTypeRequiredDescription
items{ id: string; packageId: string; packageType: Enum<'app'>; publisherId: string; … }[]Search result listings
totalintegerTotal matching results
pageintegerCurrent page number
pageSizeintegerItems per page
facets{ categories?: object[]; pricing?: object[] }optionalAggregation facets for refining search

PackageSubmission

Developer submission of a package version for review

Properties

PropertyTypeRequiredDescription
idstringSubmission ID
packageIdstringPackage identifier
versionstringVersion being submitted
publisherIdstringPublisher submitting
statusEnum<'pending' | 'scanning' | 'in-review' | 'changes-requested' | 'approved' | 'rejected'>Review status
artifactUrlstringPackage artifact URL for review
releaseNotesstringoptionalRelease notes for this version
isNewListingbooleanWhether this is a new listing submission
scanResults{ passed: boolean; securityScore?: number; compatibilityCheck?: boolean; issues?: object[] }optionalAutomated 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
idstringPublisher ID
namestringPublisher 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