SynapDocs

Profile schemas

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

For BuildersOpen-source podSynap CloudReviewed 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:

LayerWho sees itExample
GlobalEvery profile that uses itA field the system defines once and several kinds share
Profile baseEvery space that uses the profilestatus and priority on a task
Space overlayOnly the space that added itSales 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.

Views

A view shows your records as a table, a board, a calendar or a graph without copying them; the view types you can create.

Validation policy

How the pod decides whether a requested change runs directly, becomes a proposal, or is refused.

On this page

The three layersA worked exampleWhat it allowsWriting a field another space ownsWhat it does not doWhere to see a kind's fieldsRelated