# Profile schemas

> How field definitions are layered so the same kind can carry different fields in different spaces.

URL: https://doc.synap.live/docs/concepts/profile-schemas · Last reviewed against the code: 2026-11-04

A profile is the schema of a kind or a role: the fields its records carry. One person in your pod can show different
fields in your Sales space and in your Studio space. The record is the same; each space adds its own fields on top of
a shared base. Several spaces with different jobs share one set of records without their fields colliding or leaking
into each other.

## The three layers

Every field definition lives in one of three layers:

| Layer | Who sees it | Example |
|---|---|---|
| **Global** | Every profile that uses it | A field the system defines once and several kinds share |
| **Profile base** | Every space that uses the profile | `status` and `priority` on a task |
| **Space overlay** | Only the space that added it | Sales adds `investmentThesis` to the pod-wide `person` |

When you open a record in a space, its fields are the global and base fields of its profile plus that space's own
overlay fields. Another space's overlay fields are left out.

## A worked example

You run three spaces on one pod, and all three use the `person` kind. You create one person, Alice Chen.

- In Sales you add a field `investmentThesis` to `person`. It becomes a Sales overlay.
- In Knowledge you add `notesCount` to `person`. It becomes a Knowledge overlay.
- Studio adds nothing to `person`.

Open Alice in Sales and you see the base fields of `person` plus `investmentThesis`. Open her in Knowledge and you see
the base fields plus `notesCount`. Open her in Studio and you see the base fields only. There is one Alice in all
three cases.

## What it allows

- **One record, several jobs.** A freelancer with a Sales space and a Studio space can track Alice as a prospect and
  as an audience member, each space with its own fields.
- **Independent spaces.** A field added in Sales does not appear in Studio.
- **Templates that add fields.** A template that extends a profile it does not own, such as the pod-wide `person`,
  adds its fields as overlays of the space it is installed in. A template that defines its own kind gives that kind
  base fields.

## Writing a field another space owns

A write is checked through the space it is made in. A value for a field that space cannot see is treated as an
unknown field: it is stored as sent, but it is not validated and cannot be queried. The write's answer lists it as
unmodelled, with the closest known field name when there is one. It is not refused: the pod keeps extra keys so older
clients keep working, and reports them so the writer learns the field is not modelled.

## What it does not do

- **It does not decide which records you see.** Layers control which fields appear, not which records a space can
  reach. That is decided by the record's scope: a record visible to the whole pod, or to one space.
- **It does not set per-field permissions.** A member of a space sees every field in that space's view of a profile,
  and a member whose role can edit records can edit all of them.
- **It does not share fields between overlays.** Two spaces that each add `status` to `person` get two independent
  fields. To share one, define it in the profile base.

## Where to see a kind's fields

- Over MCP, `synap_get_entity` returns a record with its `effectiveProperties`: the fields it carries in the space
  you read it through.
- Over HTTP, `GET /api/hub/discover?userId=<your-user-id>&profileSlugs=<slug>` describes a kind's fields; add
  `workspaceId=<space-id>` to see that space's fields.

## Related

- [Kind and facets](/docs/concepts/kind-and-facets)
- [Entity connections](/docs/concepts/entity-connections)