Entity object

How an entity is represented when you read or write it through the SDK or as files on disk.

Every entity in Seal has the same outer shape — metadata, fields, and one body of content. The body’s format depends on the entity’s content type. This page is the hub for that shape; the other pages in this section describe each content type in detail.

At a glance

entity.id                       # 'ent_8a1c…'
entity.title                    # 'Buffer Recipe'
entity.status                   # 'IN_PROGRESS' | 'FINISHED' | …
entity.type                     # the entity-type slug
entity.system                   # the system slug
entity.fields["Volume (mL)"]    # Field { value, config }
entity.content.type             # 'page_content' | 'script_code' | 'chart' | …
entity.content.value            # depends on .type — see table below

entity.fields and entity.content are the only two places content lives. Tags, comments, permissions, change-control state, and audit history all hang off the same entity but are not “content” — they live on entity.tags, entity.comments, etc.

File representation

When you seal pull an entity, you get a directory:

ent_8a1c/
  entity.json            # metadata, fields, refs — everything except the body
  content.<ext>          # the body — extension depends on content type
  .seal/
    manifest.json        # id, version, lastUpdatedAt, content digest

entity.json is human-readable and edit-safe; seal commit will pick up your changes. The body file is whatever shape the content type demands (see table below).

Round-trip: read → edit → write preserves everything the SDK supports. Anything the SDK can’t represent natively round-trips through opaque preservation rather than being silently dropped.

Content types

entity.content.type	Body format	Body filename
page_content	Markdown (Seal flavor)	content.md
script_code / script_code_v2	Python or JavaScript source	content.py / content.js
chart	JSON (Vega-Lite spec)	content.json
file	The file itself	content.<ext>
custom	Source string or zip	content.<ext>
none	(no body)	(absent)

Most entity types have a content.type of none — they’re pure field-and-metadata records. Page content, scripts, charts, and files are the four content-bearing types.

Reading and writing

# Read
entity = seal.entities.get("ent_8a1c…")
entity.title                              # metadata
entity.fields["Volume (mL)"].value        # a field
entity.content.value                      # the body — string, dict, or Path

# Write
seal.entities.update(
    entity,
    title="Buffer Recipe (revised)",
    fields={"Volume (mL)": 250},
    content="# New body\n\n…",            # body shape matches content.type
)

The shape you read at entity.content.value is the same shape you write back. For page_content that’s a Markdown string; for script_code it’s source text; for chart it’s a Vega-Lite dict; for file it’s a file id on read or a Path on write.

Per-content-type detail

Fields

The structured part of every entity — types, configs, formulas, and how each field type reads and writes.

Page content

Rich documents stored as Seal-flavored Markdown, with field cards, tasks, mentions, and layout components.

Files

Uploaded files — images, PDFs, raw data — referenced by other entities or stored standalone.

Scripts

Python / JavaScript source attached to an entity, run on triggers or on demand.

Charts

Vega-Lite specifications rendered against entity data.

Custom content

First-class support for your own content types via deployable bundles. See Custom content.

Coming soon

The entity-object surface continues to expand. The following are planned and will appear here when they ship:

• Folders — entities that hold a structured collection of references, with their own configurable display.
• Forms — entities whose body is a fillable form template.
• Workflows — long-running orchestrations expressed as entities.

Each will follow the same outer shape — metadata, fields, one body — so existing SDK code keeps working as new types land.