Understand and use The Marketplace Company's Knowledge Graph, ontology resources, and transformation APIs.
The Marketplace Company's Knowledge Graph is the shared semantic layer behind marketplace data. It describes what entities mean, how they relate, which standards they align to, and how data can move between marketplace systems, partner systems, public pages, and AI tools.
The Knowledge Graph is not a separate database you write all marketplace records into. Operational data still lives in the systems that own it. The graph gives those systems a common language for providers, listings, places, policies, verification concepts, integrations, structured data, and agent context.
Use this guide when you want to:
Think about the Knowledge Graph in four layers:
| Layer | What it does |
|---|---|
| Ontology | Defines classes, properties, enumerations, and relationship axioms. |
| Derived ontology | Projects the active ontology for a marketplace from maintained sources, standards, and marketplace configuration. |
| Mappings and transformations | Connects ontology terms to internal models, partner schemas, import/export flows, and transformation outputs. |
| Public and API resources | Exposes ontology pages, REST endpoints, JSON-LD, Turtle, JSON-LD context, structured data, and agent-readable context. |
This lets The Marketplace Company stay practical: operators and developers work with product concepts, while the platform handles the semantic structure underneath.
The ontology is the formal model of marketplace meaning. It borrows from schema.org, RDFS, OWL, SKOS, and other common semantic web patterns, then extends them where marketplace behavior needs more specific terms.
Core term types:
name, providerType, areaServed, or memberOf.Important relationship fields:
equivalentClass, equivalentProperty, and related match fields: a term
aligns with an external standard or vocabulary.External alignment matters, but it is not automatic equivalence. Some concepts map cleanly to schema.org or another standard. Other concepts are specific to The Marketplace Company because the product needs distinctions that external standards do not model directly.
Each marketplace works from a derived ontology: the active slice of maintained ontology sources, bundled standards, and marketplace configuration.
That means a marketplace can expose its own relevant provider types, listing types, industry terms, properties, and mapping coverage without asking every operator to manage the full raw ontology. The platform resolves configuration into terms that product surfaces, APIs, imports, search, structured data, and AI tools can use consistently.
The public resources show ontology meaning. They do not imply that every operational record is published as RDF or that every term is writable through every product surface.
Mappings connect ontology terms to real data surfaces:
This distinction matters:
| Concept | Meaning |
|---|---|
| Semantic term | The concept exists in the ontology. |
| Standard alignment | The concept maps to, matches, or was informed by an external standard. |
| Product mapping | The concept connects to an internal model, field, API path, or product area. |
| Transformation mapping | Data can be projected from one supported schema to another. |
A term can exist before it has full product support. When building an integration, check the term, its mappings, and the relevant API behavior instead of assuming ontology coverage means read/write support everywhere.
These resources are the easiest way to inspect or consume the Knowledge Graph.
Some route names still use vocabulary; in product language these are ontology
resources.
| Resource | Use it for |
|---|---|
/vocabulary/:identifier | Human-readable pages for ontology terms. |
/api/knowledge-graph/vocabulary | Querying ontology terms, filters, mappings, and selected fields. |
/api/knowledge-graph/transform | Transforming payloads through supported schema mappings. |
/vocabulary.jsonld | JSON-LD representation of the live ontology resource. |
/vocabulary.ttl | Turtle output for linked-data and standards-oriented tools. |
/vocabulary-context.jsonld | JSON-LD context for interpreting ontology-backed fields. |
| MCP | Agent access to marketplace tools and ontology context when enabled. |
Use the vocabulary endpoint to inspect terms programmatically.
GET /api/knowledge-graph/vocabulary?identifier=Provider
Search by label, identifier, or description:
GET /api/knowledge-graph/vocabulary?query=coach&limit=10
Find values in a controlled type set:
GET /api/knowledge-graph/vocabulary?instanceOf=containsAny:ListingType
Find properties that apply to a class:
GET /api/knowledge-graph/vocabulary?type=property&domainIncludes=containsAny:Listing
Return only selected fields when you do not need the full term payload:
GET /api/knowledge-graph/vocabulary?identifier=Listing&fields=identifier,label,description,type
Common filters include:
identifieridentifiersquerytypesubClassOfsubClassOfFullinstanceOfenumerationOfdomainIncludesrangeIncludessubPropertyOfbroaderontologyontologiesindustriesmappingsEntitymappingsDomainIncludesmappingsStatusfieldslimitFor relationship filters such as instanceOf, domainIncludes, or
rangeIncludes, use containsAny:Value when matching against array fields.
The transform endpoint projects data between supported schemas through the mapping layer.
POST /api/knowledge-graph/transform
Content-Type: application/json
{
"inputSchema": "googlePlaces",
"outputSchema": "tmpc",
"domain": "Listings",
"inputData": [
{
"name": "Example court",
"formatted_address": "123 Main St"
}
],
"options": {
"keepUnmapped": true
}
}
The exact supported schemas and domains depend on the mappings available in the platform. The useful mental model is:
source schema -> ontology-aligned mapping -> target schema
Use transformations when you want an integration to move through shared marketplace meaning instead of writing one-off field conversion logic.
The Knowledge Graph also supports public, machine-readable context. Public pages can use ontology-backed structured data so providers, listings, places, reviews, policies, and domain-specific concepts are easier for search engines, crawlers, partners, and agents to understand.
Use the JSON-LD, Turtle, and JSON-LD context resources when you need a machine-readable description of the ontology itself. Use page-level structured data when you need a machine-readable description of a specific public entity or page.
The Knowledge Graph helps AI and search systems work from structured context instead of guessing from raw text or table names.
It can provide:
The strongest pattern is stacked retrieval: use explicit ontology filters for hard constraints, then use keyword or semantic search for recall. Embeddings can help find related terms, but they do not replace the graph relationships or mapping metadata.
Analytics uses Knowledge Graph concepts when events, dimensions, metrics, or AI-generated summaries need consistent meaning. That does not make analytics the main public interface for the Knowledge Graph.
For developer work, treat analytics as a consumer of shared semantics. Use the Knowledge Graph docs when you need ontology terms, mappings, transformations, or machine-readable context. Use analytics docs and console surfaces when you need event collection, reporting, or dashboard behavior.
Do not assume:
When in doubt, inspect the term page, query the API, check mappings, and use the API reference for the current endpoint contract.