Source of truth for implementation is the canonical schema host: https://schemas.meta-aiml.org/v3.0.0/. If any page text conflicts with canonical schema files, follow canonical files. Documentation home.

Marketplace

v3.0.0

DigitalEntity

Commerce

v3 schema for digital marketplaces mediating transactions between buyers and sellers through listing, matching, payment orchestration, and trust workflows.

Top-level required

Required modules

Capability groups

Entity properties

Canonical Files

Contract URL: https://schemas.meta-aiml.org/v3.0.0/entity/marketplace.json

Example URL: https://schemas.meta-aiml.org/v3.0.0/examples/marketplace_example_schema_v3.json

Inheritance Chain

https://schemas.meta-aiml.org/v3.0.0/ontology/digital_entity.json

https://schemas.meta-aiml.org/v3.0.0/archetypes/mediated_exchange.json

Interaction archetype

MediatedExchange

Required Top-level Fields

These fields are enforced by JSON Schema required[] at root level.

@type

ontologicalMode

interactionArchetype

domain

name

description

deliveryFormat

capabilities

structuralMetadata

modules

Non-universal required fields

interactionArchetype

Entity-specific Properties

Keys under properties.properties dedicated to this entity contract.

contactPoints

identifiers

listingGovernanceModel

marketType

priceFormationModel

socialProfiles

supportsDisputeResolution

supportsEscrow

Modules Contract

Required modules

No required modules for this entity.

Optional modules

catalog

payments

trustAndSafety

Capabilities Contract

Required capability groups

commerce

financial

interaction

Optional capability groups

community

content

Governance Validation Rules

Normative rule list from governanceMetadata.sdkValidationRules.

RULE-MRKT-001: @type MUST equal "Marketplace"

RULE-MRKT-002: ontologicalMode MUST equal "DigitalEntity"

RULE-MRKT-003: interactionArchetype MUST contain "MediatedExchange"

RULE-MRKT-004: capabilities MUST include commerce, financial, interaction

RULE-MRKT-005: structuralMetadata.topology MUST equal "triadic"

RULE-MRKT-006: structuralMetadata.valueSource MUST equal "transaction_mediation"

Canonical Contract JSON

https://schemas.meta-aiml.org/v3.0.0/entity/marketplace.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "@context": [
    "https://schemas.meta-aiml.org/v3.0.0/context.jsonld"
  ],
  "@id": "https://schemas.meta-aiml.org/v3.0.0/entity/marketplace.json",
  "$id": "https://schemas.meta-aiml.org/v3.0.0/entity/marketplace.json",
  "@type": "Marketplace",
  "schemaVersion": "3.0.0",
  "aimlVersion": "3.0.0",
  "title": "Marketplace Entity Schema",
  "description": "v3 schema for digital marketplaces mediating transactions between buyers and sellers through listing, matching, payment orchestration, and trust workflows.",
  "examples": [
    {
      "description": "Peer-to-peer marketplace with escrow payment and dispute handling",
      "reference": "marketplace_example_p2p"
    },
    {
      "description": "Service marketplace connecting clients with verified professionals",
      "reference": "marketplace_example_services"
    }
  ],
  "type": "object",
  "additionalProperties": false,
  "allOf": [
    {
      "$ref": "../ontology/digital_entity.json"
    },
    {
      "$ref": "../archetypes/mediated_exchange.json"
    }
  ],
  "properties": {
    "@type": {
      "const": "Marketplace"
    },
    "ontologicalMode": {
      "const": "DigitalEntity"
    },
    "interactionArchetype": {
      "type": "array",
      "contains": {
        "const": "MediatedExchange"
      },
      "items": {
        "type": "string",
        "enum": [
          "MediatedExchange"
        ]
      }
    },
    "domain": {
      "const": "Commerce"
    },
    "businessModel": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Commission",
          "ListingFees",
          "Subscription",
          "Advertising"
        ]
      }
    },
    "deliveryFormat": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "WebApp",
          "MobileApp",
          "API"
        ]
      }
    },
    "name": {
      "$ref": "../components/multilingual_format.json#/$defs/LocalizedText"
    },
    "description": {
      "$ref": "../components/multilingual_format.json#/$defs/LocalizedText"
    },
    "shortDescription": {
      "$ref": "../components/multilingual_format.json#/$defs/LocalizedTextOrString"
    },
    "url": {
      "type": "string",
      "format": "uri"
    },
    "foundingDate": {
      "type": "string",
      "format": "date"
    },
    "properties": {
      "type": "object",
      "properties": {
        "marketType": {
          "type": "string",
          "enum": [
            "peer_to_peer",
            "business_to_consumer",
            "business_to_business",
            "hybrid"
          ]
        },
        "listingGovernanceModel": {
          "type": "string",
          "enum": [
            "open",
            "curated",
            "invite_only"
          ]
        },
        "priceFormationModel": {
          "type": "string",
          "enum": [
            "fixed_price",
            "negotiated",
            "auction",
            "mixed"
          ]
        },
        "supportsEscrow": {
          "type": "boolean"
        },
        "supportsDisputeResolution": {
          "type": "boolean"
        },
        "contactPoints": {
          "type": "array",
          "items": {
            "$ref": "../components/common_defs.json#/$defs/ContactPoint"
          }
        },
        "socialProfiles": {
          "type": "array",
          "items": {
            "$ref": "../components/common_defs.json#/$defs/SocialProfile"
          }
        },
        "identifiers": {
          "type": "array",
          "items": {
            "$ref": "../components/common_defs.json#/$defs/Identifier"
          }
        }
      }
    },
    "capabilities": {
      "type": "object",
      "required": [
        "commerce",
        "financial",
        "interaction"
      ],
      "properties": {
        "commerce": {
          "$ref": "../components/capability_groups.json#/$defs/CommerceCapabilities"
        },
        "financial": {
          "$ref": "../components/capability_groups.json#/$defs/FinancialCapabilities"
        },
        "interaction": {
          "$ref": "../components/capability_groups.json#/$defs/InteractionCapabilities"
        },
        "content": {
          "$ref": "../components/capability_groups.json#/$defs/ContentCapabilities"
        },
        "community": {
          "$ref": "../components/capability_groups.json#/$defs/CommunityCapabilities"
        }
      }
    },
    "modules": {
      "type": "object",
      "properties": {
        "catalog": {
          "type": "object",
          "properties": {
            "taxonomyVersioned": {
              "type": "boolean"
            },
            "bulkImportSupported": {
              "type": "boolean"
            },
            "listingModerationEnabled": {
              "type": "boolean"
            }
          }
        },
        "payments": {
          "type": "object",
          "properties": {
            "escrowEnabled": {
              "type": "boolean"
            },
            "splitPayoutsEnabled": {
              "type": "boolean"
            },
            "chargebackWorkflowEnabled": {
              "type": "boolean"
            }
          }
        },
        "trustAndSafety": {
          "type": "object",
          "properties": {
            "sellerVerificationEnabled": {
              "type": "boolean"
            },
            "fraudScreeningEnabled": {
              "type": "boolean"
            },
            "abuseAppealsEnabled": {
              "type": "boolean"
            }
          }
        }
      }
    },
    "structuralMetadata": {
      "type": "object",
      "properties": {
        "topology": {
          "const": "triadic"
        },
        "roles": {
          "const": [
            "buyer",
            "seller",
            "platform"
          ]
        },
        "valueSource": {
          "const": "transaction_mediation"
        },
        "transactionFlow": {
          "const": "escrow"
        },
        "networkEffects": {
          "const": "cross_side"
        },
        "liquidityModel": {
          "type": "string",
          "enum": [
            "demand_first",
            "supply_first",
            "balanced_growth"
          ]
        }
      }
    },
    "targetAudience": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "siteCapabilities": {
      "type": "object",
      "properties": {
        "supportedDevices": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "desktop",
              "mobile",
              "tablet"
            ]
          }
        },
        "languages": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "accessibilityFeatures": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "@type",
    "ontologicalMode",
    "interactionArchetype",
    "domain",
    "name",
    "description",
    "deliveryFormat",
    "capabilities",
    "structuralMetadata",
    "modules"
  ],
  "validationMetadata": {
    "schemaVersion": "3.0.0",
    "phase": "entity",
    "status": "draft",
    "lastValidated": "2026-02-20T12:00:00Z",
    "validator": "META-AIML QA"
  },
  "semanticAnnotations": {
    "classificationRationale": "Marketplace is modeled as DigitalEntity + MediatedExchange because platform value is created by orchestrating transactions between distinct market sides.",
    "disambiguationNotes": "Different from first-party ecommerce where the platform is also the sole seller."
  },
  "governanceMetadata": {
    "entityVersion": "3.0.0",
    "introducedIn": "META-AIML v3.0.0",
    "stabilityLevel": "draft",
    "sdkValidationRules": [
      "RULE-MRKT-001: @type MUST equal \"Marketplace\"",
      "RULE-MRKT-002: ontologicalMode MUST equal \"DigitalEntity\"",
      "RULE-MRKT-003: interactionArchetype MUST contain \"MediatedExchange\"",
      "RULE-MRKT-004: capabilities MUST include commerce, financial, interaction",
      "RULE-MRKT-005: structuralMetadata.topology MUST equal \"triadic\"",
      "RULE-MRKT-006: structuralMetadata.valueSource MUST equal \"transaction_mediation\""
    ]
  }
}

Filled Example Instance

https://schemas.meta-aiml.org/v3.0.0/examples/marketplace_example_schema_v3.json

{
  "@context": [
    "https://schemas.meta-aiml.org/v3.0.0/context.jsonld"
  ],
  "@id": "https://data.meta-aiml.org/v3.0.0/examples/marketplace/nexus-bazaar-exchange",
  "$id": "https://data.meta-aiml.org/v3.0.0/examples/marketplace/nexus-bazaar-exchange",
  "@type": "Marketplace",
  "schemaVersion": "3.0.0",
  "aimlVersion": "3.0.0",
  "title": "Example Filled Marketplace Entity Example (Nexus Bazaar Exchange)",
  "ontologicalMode": "DigitalEntity",
  "interactionArchetype": [
    "MediatedExchange"
  ],
  "domain": "Commerce",
  "businessModel": [
    "Commission",
    "ListingFees",
    "Subscription",
    "Advertising"
  ],
  "deliveryFormat": [
    "WebApp",
    "MobileApp",
    "API"
  ],
  "name": {
    "en": "Nexus Bazaar Exchange",
    "es": "Nexus Bazaar Exchange",
    "fr": "Nexus Bazaar Exchange"
  },
  "description": {
    "en": "Nexus Bazaar Exchange is a fictional multi-category marketplace connecting buyers and independent sellers with mediated checkout, escrow-backed transaction handling, and trust workflows for dispute resolution.",
    "es": "Nexus Bazaar Exchange es un marketplace ficticio multicategoria que conecta compradores y vendedores independientes con checkout mediado, flujo de escrow y gestion de disputas.",
    "fr": "Nexus Bazaar Exchange est une place de marche fictive multicategorie reliant acheteurs et vendeurs avec paiement medie, escrow et gestion des litiges."
  },
  "shortDescription": {
    "en": "Multi-category marketplace with escrow, seller onboarding, and trust-first transaction mediation.",
    "es": "Marketplace multicategoria con escrow, onboarding de vendedores y mediacion de transacciones.",
    "fr": "Place de marche multicategorie avec escrow, onboarding vendeurs et mediation de transactions."
  },
  "url": "https://nexus-bazaar.example",
  "foundingDate": "2018-03-14",
  "createdDate": "2026-02-20T18:40:00Z",
  "lastModified": "2026-02-20T18:40:00Z",
  "examples": [
    {
      "scenario": "Holiday demand spike in electronics category",
      "note": "AI should prioritize marketplace flow interpretation: buyer-seller matching, mediated checkout, escrow hold, and dispute pathways."
    },
    {
      "scenario": "New seller onboarding and listing quality review",
      "note": "AI should infer listing governance constraints and trust controls before suggesting publishing or promotion actions."
    }
  ],
  "properties": {
    "marketType": "hybrid",
    "listingGovernanceModel": "curated",
    "priceFormationModel": "mixed",
    "supportsEscrow": true,
    "supportsDisputeResolution": true,
    "contactPoints": [
      {
        "contactType": "support",
        "telephone": "+1-415-555-0133",
        "email": "support@nexus-bazaar.example",
        "url": "https://nexus-bazaar.example/support",
        "areaServed": "global",
        "availableLanguages": [
          "en",
          "es",
          "fr"
        ]
      },
      {
        "contactType": "sales",
        "telephone": "+1-415-555-0172",
        "email": "seller-success@nexus-bazaar.example",
        "url": "https://nexus-bazaar.example/seller-center",
        "areaServed": "global",
        "availableLanguages": [
          "en"
        ]
      }
    ],
    "socialProfiles": [
      {
        "platform": "linkedin",
        "url": "https://www.linkedin.com/company/nexus-bazaar",
        "username": "nexus-bazaar"
      },
      {
        "platform": "instagram",
        "url": "https://instagram.com/nexus_bazaar",
        "username": "nexus_bazaar"
      },
      {
        "platform": "facebook",
        "url": "https://facebook.com/nexusbazaar",
        "username": "nexusbazaar"
      }
    ],
    "identifiers": [
      {
        "type": "url",
        "value": "https://nexus-bazaar.example"
      },
      {
        "type": "custom",
        "value": "MRKT-NBX-001"
      }
    ]
  },
  "capabilities": {
    "commerce": {
      "features": [
        "productCatalog",
        "cart",
        "checkout",
        "orderTracking",
        "inventory",
        "vendorManagement",
        "listingManagement",
        "pricing",
        "search",
        "filtering",
        "wishlists",
        "comparisons"
      ],
      "hasProductCatalog": true,
      "catalogSize": 420000,
      "supportsCart": true,
      "supportsCheckout": true,
      "hasOrderTracking": true,
      "recommendationEngine": true,
      "vendorManagement": true,
      "searchCapability": true,
      "filteringOptions": [
        "price",
        "rating",
        "category",
        "availability",
        "brand",
        "shipping_time"
      ]
    },
    "financial": {
      "features": [
        "payments",
        "invoicing",
        "refunds",
        "wallet",
        "billing",
        "subscriptionManagement",
        "escrow"
      ],
      "paymentMethods": [
        "credit_card",
        "debit_card",
        "digital_wallet",
        "bank_transfer"
      ],
      "acceptsCreditCards": true,
      "currencies": [
        "USD",
        "EUR",
        "GBP"
      ],
      "priceRange": "variable",
      "commissionModel": "percentage",
      "commissionRate": 9.5,
      "supportsSubscriptions": true,
      "supportsInvoicing": true,
      "refundPolicy": "partial_refund"
    },
    "interaction": {
      "features": [
        "messaging",
        "commenting",
        "rating",
        "reviews",
        "notifications",
        "matching"
      ],
      "interactionMethods": [
        "in_app_messaging",
        "online_form",
        "email"
      ],
      "availableActions": [
        "search_listings",
        "contact_seller",
        "place_order",
        "open_dispute",
        "track_order"
      ],
      "hasMessaging": true,
      "hasComments": true,
      "hasRating": true,
      "hasReviews": true,
      "hasSocialGraph": false,
      "hasFeed": true,
      "hasNotifications": true,
      "hasMatching": true,
      "realTimeCommunication": true,
      "moderationEnabled": true,
      "privacyControls": [
        "public",
        "private",
        "semi_anonymous"
      ]
    },
    "content": {
      "features": [
        "publishing",
        "search",
        "categories",
        "tags"
      ],
      "contentTypes": [
        "listing",
        "review",
        "faq",
        "policy"
      ],
      "contentFormats": [
        "text",
        "html",
        "json",
        "webp"
      ],
      "contentAccess": [
        "public"
      ],
      "editorialControl": true,
      "userGeneratedContent": true,
      "mediaHosting": true,
      "searchPossible": true,
      "hasCategorization": true,
      "hasTagging": true,
      "archiveAccess": false,
      "rssFeeds": false
    },
    "community": {
      "features": [
        "groups",
        "communities",
        "discovery",
        "moderation",
        "membershipManagement"
      ],
      "supportsGroups": true,
      "supportsChannels": false,
      "communitiesCount": 380,
      "hasDiscovery": true,
      "hasModeration": true,
      "moderationModel": "ai_assisted_human",
      "hasMembershipManagement": true,
      "membershipTypes": [
        "buyer",
        "seller",
        "verified_seller"
      ],
      "supportsGroupEvents": false,
      "supportsPolls": true,
      "hasGovernance": true,
      "governanceModel": "centralized",
      "privacyLevels": [
        "public",
        "closed"
      ]
    }
  },
  "modules": {
    "catalog": {
      "taxonomyVersioned": true,
      "bulkImportSupported": true,
      "listingModerationEnabled": true
    },
    "payments": {
      "escrowEnabled": true,
      "splitPayoutsEnabled": true,
      "chargebackWorkflowEnabled": true
    },
    "trustAndSafety": {
      "sellerVerificationEnabled": true,
      "fraudScreeningEnabled": true,
      "abuseAppealsEnabled": true
    }
  },
  "structuralMetadata": {
    "topology": "triadic",
    "roles": [
      "buyer",
      "seller",
      "platform"
    ],
    "valueSource": "transaction_mediation",
    "transactionFlow": "escrow",
    "networkEffects": "cross_side",
    "liquidityModel": "balanced_growth"
  },
  "targetAudience": [
    "buyers",
    "independent_sellers",
    "small_businesses",
    "collectors"
  ],
  "siteCapabilities": {
    "supportedDevices": [
      "desktop",
      "mobile",
      "tablet"
    ],
    "languages": [
      "en",
      "es",
      "fr"
    ],
    "accessibilityFeatures": [
      "keyboard_navigation",
      "screen_reader_labels",
      "text_scaling",
      "high_contrast_mode"
    ]
  },
  "validationMetadata": {
    "schemaVersion": "3.0.0",
    "phase": "example_instance",
    "status": "reference",
    "lastValidated": "2026-02-20T18:40:00Z",
    "validator": "META-AIML SDK v3"
  },
  "semanticAnnotations": {
    "classificationRationale": "Marketplace is modeled as DigitalEntity plus MediatedExchange because platform value is generated by mediating buyer-seller transactions rather than direct first-party inventory sales.",
    "disambiguationNotes": "This is not a direct ecommerce storefront where the platform acts as the sole seller. Escrow, dispute workflows, and multi-party liquidity are first-class behaviors.",
    "intendedUse": "Canonical filled reference for marketplace websites that need robust AI understanding of mediated exchange architecture."
  },
  "governanceMetadata": {
    "entityVersion": "3.0.0",
    "introducedIn": "META-AIML v3.0.0",
    "stabilityLevel": "reference",
    "sdkValidationRules": [
      "RULE-MRGF-001: @type MUST equal \"Marketplace\"",
      "RULE-MRGF-002: ontologicalMode MUST equal \"DigitalEntity\"",
      "RULE-MRGF-003: interactionArchetype MUST contain exactly one value: \"MediatedExchange\"",
      "RULE-MRGF-004: capabilities MUST include commerce, financial, and interaction groups",
      "RULE-MRGF-005: modules.payments MUST define escrow and payout controls",
      "RULE-MRGF-006: structuralMetadata constants MUST align with MediatedExchange archetype",
      "RULE-MRGF-007: properties.identifiers SHOULD provide at least one durable identifier",
      "RULE-MRGF-008: examples MUST include scenario and note fields for operational interpretation"
    ]
  }
}

All entities EcommerceStore EducationPlatform