The The Marketplace Company
Knowledge Graph organizes how
data is described and related so you can build integrations once and reuse them
everywhere.
At a glance, our Knowledge Graph has three components:
- Ontology: A shared, semantic model
for classes, properties, and enumerations, with axioms defining how they
relate.
- Transformation:
Translate data from one schema into another using the shared ontology as the
bridge.
- Analytics: Customer data events
following the Segment Spec, powering real‑time analytics and CDP integrations.
Ontology
The Marketplace Company uses a semantic ontology to model data in a way that is both
machine-readable and developer-friendly. Our ontology describes data meanings
and relationships across classes, properties, and enumerations. We follow
schema.org and align to common semantic web patterns
(RDFS/OWL),
extending them where needed for marketplace concepts.
If you're new to ontologies, here's the mental model:
Schema
We use standard schema.org properties as a starting point
to describe our ontology.
General
- label: The human‑readable name for a term. Keep it
semantic and stable over time.
- description: A concise explanation of the term's
meaning and intent. Prefer vendor‑neutral, implementation‑agnostic language.
- identifier: The unique, canonical ID used in links
and APIs. Stable and global within our vocabulary.
- type: Whether the term is a
Class or Property.
Class Schema
- subClassOf: Declares that a class is a
specialization of another class. All instances of the subclass are also
instances of the superclass; properties of the superclass are inherited by the
subclass. Example:
Book subClassOf CreativeWork ⇒ every book is a creative
work.
- instanceOf: Declares that a class is a member of an
enumeration (a controlled value set). This is distinct from
subClassOf: it
doesn't imply property inheritance, it indicates class membership within an
enum taxonomy. Example: FeatureSearch instanceOf Feature.
- enumerationOf: Our extension that links an
enumeration to the class it enumerates. It clarifies the modeling when a class
is an instance of an enumeration while also being a
subClassOf of another
class for property inheritance. This avoids duplicating definitions and
cleanly separates value‑set membership from type inheritance.
- equivalentClass: Declares alignment with an
external ontology's class (OWL
equivalentClass). Use to map our terms to
schema.org, Wikidata, or other vocabularies for interoperability.
- broader: Declares an immediate hierarchical link to a
more general concept (non-transitive). Use it to relate across families
without using inheritance.
Dual role (punning)
In our vocabulary, a term may act both as a class (for inheritance via
subClassOf) and as a member of an enumeration (via instanceOf). This
intentional metamodeling (akin to
OWL 2 punning) lets you reuse the
same identifier as a selectable value and as a type that contributes properties.
There are rare occasions where property may be marked as an instance of an
enumeration, this is allowed through punning.
Property Schema
- domainIncludes: Suggests the class(es) a
property is typically used on. In schema.org, this is advisory (non‑strict):
it guides producers/consumers without forbidding other well‑formed uses.
- rangeIncludes: Suggests the expected value
type(s) for a property (e.g.,
Text, URL, or a specific class). Like
domain, this is guidance that improves data quality and tooling.
- subPropertyOf: Declares a property to be a more
specific version of a broader property (RDFS
subPropertyOf). All relations
stated with the subproperty are implied for the superproperty. Example:
department subPropertyOf subOrganization.
- equivalentProperty: Declares alignment with
a property from an external ontology (OWL
equivalentProperty). Use to signal
semantic equivalence to schema.org or Wikidata properties.
Resources
The vocabulary is consumable in the following resources:
- Schema Viewer: A visual tool to explore the vocabulary
and the relationships between the terms. Terms can be found at
/vocabulary/IDENTIFIER (e.g. /vocabulary/Thing)
- REST API Endpoints: API endpoints
to query the vocabulary and transform data
- MCP Server: A Model Context Provider server that can be
used to give access to the vocabulary to AI agents. (Coming Soon)
- JSON-LD: A JSON-LD file of all the terms in the
vocabulary.
- Turtle: A Turtle file of all the terms in the vocabulary.
Can be loaded into a application like Protégé
for visualizing the vocabulary.
- JSON-LD Context: A machine readable context
file.
Map any external schema to the Vocabulary once, then translate between schemas.
The Vocabulary is the bridge: if both sides are mapped, you can transform
between them. Mappings live alongside terms, so changes are declarative—not
scattered across glue code. You can chain transformations (A → Vocabulary → B),
but most flows go A → B via the bridge.
Mappings Directory
The Mappings Directory is a catalog of supported schemas mapped to the
Vocabulary (first‑party models and third‑party APIs). It's the foundation of the
Transform Service: as the directory grows, translating between systems becomes a
configuration step—not an engineering project.
- Third‑party providers can request inclusion. A public submission workflow is
in progress; in the meantime, mappings are curated with partners.
Resources
- API reference:
Transform API reference
- Input: source schema id, target schema id, and your payload
- Output: payload projected into the target schema
Analytics
Customer data analytics is a core component of the Knowledge Graph, pairing with
the Ontology to create a unified semantic layer. We follow the
Segment Spec—an
industry‑standard schema for customer data—and extend it with properties and
context from our Vocabulary. This combination makes events both interoperable
with any
Customer Data Platform
(CDP) and enriched with marketplace‑specific meaning.
- Segment Spec Alignment: Our customer data schema implements Segment's
semantic API calls:
Page (what page
is the user on?),
Track (what
action did they take?), and
Identify (who
is the user?). We also follow their
common fields
for context, properties, and traits.
- Industry Event Specs: For
semantic events,
we align to Segment's
B2B SaaS and
Ecommerce
specs, extended with marketplace‑specific properties from our Vocabulary.
- Real‑Time Performance: All customer data analytics are powered by
ClickHouse via Tinybird —
a columnar database optimized for analytical queries — enabling real‑time
dashboards for providers, marketplaces, and listings.
- CDP Compatibility: Because our schema follows the Segment Spec, you can
route the same customer data to any CDP or downstream destination. We maintain
an ETL layer that sends customer data to configured destinations without
additional transformation.
You can find more details about our Customer Data Schema in the marketplace
console.
AI and Knowledge Graphs
Our Knowledge Graph makes AI practical, not just possible.
- Hybrid search: We combine keyword and vector search to rank results that
are both precise and semantically relevant.
- Embeddings: We embed Vocabulary terms and transactional data (e.g.
providers, listings) so AI models can reason over meaning and similarity.
- MCP tools: We expose tools via an MCP server so external AI systems can
browse the Vocabulary, query data, and perform transforms with context.
- RAG workflows: The Marketplace AI Assistant uses retrieval to access
marketplace data and relationships, enabling helpful, grounded responses.
- One‑click provider creation: Give us a website URL; we crawl, extract
structured data, auto‑classify via the Vocabulary, and create the provider.
Why this matters
Interoperability is how you move fast without breaking everything else.
- Decouple systems: Model once with the Vocabulary; translate as needed with
the Transform API.
- Better analytics: Customer data uses the same terms, so dashboards and
destinations stay consistent.
- AI‑ready: Semantic structure and embeddings make search, recommendations,
and assistants more accurate and useful.
"Something is complex if it contains a great deal of information that has high
utility, while something that contains a lot of useless or meaningless
information is simply complicated." — Steve Grand
Glossary of Terms
- Axiom: A logical statement about
classes and properties (e.g., domain, range, subClassOf).
- Ontology:
A shared, semantic model for classes, properties, and enumerations, with
axioms defining how they relate.
- Enumeration: A controlled value
set modeled as a specialized class.