Skip to content

Update Lexicon create schema reference #2140

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Oct 2, 2025
Merged

Update Lexicon create schema reference #2140

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
219b480
add cohorts sections to Lexicon
Alex-Kim-mp Sep 5, 2025
d642c74
Merge branch 'main' of github.com:mixpanel/docs
Alex-Kim-mp Oct 2, 2025
b23176b
update upload schemas
Alex-Kim-mp Oct 2, 2025
544bff1
merge
Alex-Kim-mp Oct 2, 2025
f20141f
update reference
Alex-Kim-mp Oct 2, 2025
433c086
update yaml
Alex-Kim-mp Oct 2, 2025
04529ce
update json example
Alex-Kim-mp Oct 2, 2025
b8b6763
fix
Alex-Kim-mp Oct 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 11 additions & 120 deletions openapi/src/lexicon-schemas.openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,117 +183,7 @@ paths:
summary: Create/Replace One
tags:
- Create Schemas
description: >-
Upload a schema for a single entity. If a schema already exists for a
specified entity, it will be replaced by the one you upload.

[block:callout] {
"type": "warning",
"title": "Metadata merging behavior",
"body": "If the new schema is missing `metadata` properties that are currently set in the existing schema for that entity, those properties will be merged into the new schema. For example, if your current schema has `{\"metadata\": {\"com.mixpanel\": {\"hidden\": true}}}` and you upload a new schema without \"hidden\", we will merge `\"hidden\": true` to your uploaded schema's metadata. If you want to remove that property, set the value to `null`."
} [/block]

[block:callout] {
"type": "info",
"title": "Adding a schema for User Profiles",
"body": "To add a schema for your [User Profiles](https://help.mixpanel.com/hc/en-us/articles/115004501966-User-Profiles), specify the `entityType` as `profile` and the `name` as `$user`."
} [/block]

### Example POST Body

```json

{
"$schema": "http://json-schema.org/draft-07/schema",
"description": "Tracked when a user adds an item to their cart.",
"required": [
"item_name",
"item_id",
"item_price"
],
"additionalProperties": true,
"metadata": {
"com.mixpanel": {
"tags": [
"Shopping",
"KPIs"
],
"displayName": "Item Purchased",
"hidden": false,
"dropped": false,
"owners": [
{
"name": "First Last",
"email": "first.last@mixpanel.com"
}
]
}
},
"properties": {
"item_name": {
"type": "string",
"description": "The name of the item",
"examples": [
"Blue Widget"
],
"metadata": {
"com.mixpanel": {
"displayName": "Item Name"
}
}
},
"item_id": {
"type": "integer",
"description": "The internal id of the item",
"examples": [
12345
],
"metadata": {
"com.mixpanel": {
"displayName": "Item ID"
}
}
},
"item_price": {
"type": "number",
"description": "The current price of the item",
"examples": [
25.35
],
"metadata": {
"com.mixpanel": {
"displayName": "Price"
}
}
},
"promo_id": {
"type": "integer",
"description": "The id of any promo in progress for this item",
"examples": [
82523,
18382
],
"metadata": {
"com.mixpanel": {
"displayName": "Promo ID"
}
}
},
"date_added_to_catalog": {
"type": "string",
"format": "date-time",
"description": "The date this item was added to the store catalog",
"examples": [
"2015-03-05T15:25:23"
],
"metadata": {
"com.mixpanel": {
"displayName": "Date Added"
}
}
}
}
} ```
description: ""
requestBody:
content:
application/json:
Expand Down Expand Up @@ -410,20 +300,21 @@ components:
[Events only] If true, the event will be dropped at
ingestion time.
default: false
owners:
contacts:
type: array
description: >-
A list of people or teams that are responsible for this
A list of emails belonging to users responsible for this
entity.
items:
type: object
properties:
name:
type: string
email:
type: string
format: email
type: string
additionalProperties: false
teamContacts:
type: array
description: >-
A list of team names responsible for this
entity.
items:
type: string
additionalProperties: false
SchemaEntry:
type: object
Expand Down
210 changes: 104 additions & 106 deletions reference/Lexicon Schemas API/create-schemas/upload-schema-by-entity-and-name.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,118 +3,116 @@ title: Create/Replace One
category:
uri: Lexicon Schemas API
content:
excerpt: >-
Upload a schema for a single entity. If a schema already exists for a
specified entity, it will be replaced by the one you upload.
excerpt: ''
privacy:
view: public
---
Upload a schema for a single entity. If a schema already exists for a specified entity, it will be replaced by the one you upload.

<Callout icon="🚧" theme="warn">
Metadata merging behavior

[block:callout] {
"type": "warning",
"title": "Metadata merging behavior",
"body": "If the new schema is missing `metadata` properties that are currently set in the existing schema for that entity, those properties will be merged into the new schema. For example, if your current schema has `{\"metadata\": {\"com.mixpanel\": {\"hidden\": true}}}` and you upload a new schema without \"hidden\", we will merge `\"hidden\": true` to your uploaded schema's metadata. If you want to remove that property, set the value to `null`."
} [/block]
If the new schema is missing `metadata` properties that are currently set in the existing schema for that entity, those properties will be merged into the new schema. For example, if your current schema has `{"metadata": {"com.mixpanel": {"hidden": true}}}` and you upload a new schema without "hidden", we will merge `"hidden": true` to your uploaded schema's metadata. If you want to remove that property, set the value to `null`.
</Callout>

[block:callout] {
"type": "info",
"title": "Adding a schema for User Profiles",
"body": "To add a schema for your [User Profiles](https://help.mixpanel.com/hc/en-us/articles/115004501966-User-Profiles), specify the `entityType` as `profile` and the `name` as `$user`."
} [/block]
<Callout icon="📘" theme="info">
Adding a schema for User Profiles

### Example POST Body
To add a schema for your [User Profiles](https://help.mixpanel.com/hc/en-us/articles/115004501966-User-Profiles), specify the `entityType` as `profile` and the `name` as `$user`.
</Callout>

```json
### Example POST Body

{
"$schema": "http://json-schema.org/draft-07/schema",
"description": "Tracked when a user adds an item to their cart.",
"required": [
"item_name",
"item_id",
"item_price"
],
"additionalProperties": true,
"metadata": {
"com.mixpanel": {
"tags": [
"Shopping",
"KPIs"
],
"displayName": "Item Purchased",
"hidden": false,
"dropped": false,
"owners": [
{
"name": "First Last",
"email": "first.last@mixpanel.com"
}
]
```json
{
"$schema": "http://json-schema.org/draft-07/schema",
"description": "Tracked when a user adds an item to their cart.",
"required": [
"item_name",
"item_id",
"item_price"
],
"additionalProperties": true,
"metadata": {
"com.mixpanel": {
"tags": [
"Shopping",
"KPIs"
],
"displayName": "Item Purchased",
"hidden": false,
"dropped": false,
"contacts": [
"first.last@mixpanel.com"
],
"teamContacts": [
"Analytics Team"
]
}
},
"properties": {
"item_name": {
"type": "string",
"description": "The name of the item",
"examples": [
"Blue Widget"
],
"metadata": {
"com.mixpanel": {
"displayName": "Item Name"
}
}
},
"item_id": {
"type": "integer",
"description": "The internal id of the item",
"examples": [
12345
],
"metadata": {
"com.mixpanel": {
"displayName": "Item ID"
}
}
},
"properties": {
"item_name": {
"type": "string",
"description": "The name of the item",
"examples": [
"Blue Widget"
],
"metadata": {
"com.mixpanel": {
"displayName": "Item Name"
}
}
},
"item_id": {
"type": "integer",
"description": "The internal id of the item",
"examples": [
12345
],
"metadata": {
"com.mixpanel": {
"displayName": "Item ID"
}
}
},
"item_price": {
"type": "number",
"description": "The current price of the item",
"examples": [
25.35
],
"metadata": {
"com.mixpanel": {
"displayName": "Price"
}
}
},
"promo_id": {
"type": "integer",
"description": "The id of any promo in progress for this item",
"examples": [
82523,
18382
],
"metadata": {
"com.mixpanel": {
"displayName": "Promo ID"
}
}
},
"date_added_to_catalog": {
"type": "string",
"format": "date-time",
"description": "The date this item was added to the store catalog",
"examples": [
"2015-03-05T15:25:23"
],
"metadata": {
"com.mixpanel": {
"displayName": "Date Added"
}
}
"item_price": {
"type": "number",
"description": "The current price of the item",
"examples": [
25.35
],
"metadata": {
"com.mixpanel": {
"displayName": "Price"
}
}
},
"promo_id": {
"type": "integer",
"description": "The id of any promo in progress for this item",
"examples": [
82523,
18382
],
"metadata": {
"com.mixpanel": {
"displayName": "Promo ID"
}
}
},
"date_added_to_catalog": {
"type": "string",
"format": "date-time",
"description": "The date this item was added to the store catalog",
"examples": [
"2015-03-05T15:25:23"
],
"metadata": {
"com.mixpanel": {
"displayName": "Date Added"
}
}
}
} ```
privacy:
view: public
---

}
}
```
10 changes: 5 additions & 5 deletions reference/Lexicon Schemas API/create-schemas/upload-schemas-for-project.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,11 +47,11 @@ Upload schemas in bulk to the specified project. If a schema already exists for
"displayName": "Item Purchased",
"hidden": false,
"dropped": false,
"owners": [
{
"name": "First Last",
"email": "first.last@mixpanel.com"
}
"contacts": [
"first.last@mixpanel.com"
],
"teamContacts": [
"Analytics Team"
]
}
},
Expand Down
Loading