Configuring Schema

Schema tells SafetyKit how to interpret fields in your objects, and is managed as part of namespace settings. Configure schema via PUT /v1/data/{namespace}/settings.

Why schema matters

Schema improves processing quality and usability by signaling, for example:

• which fields contain media URLs, which can be extracted & scraped for further processing
• which fields are rich text (markdown or HTML) and should render accordingly
• which fields are metadata-only, and should not be indexed
• how objects should render in the SafetyKit UI

Example schema

{
  "schema": {
    "title": { "display_hint": { "type": "title" } },
    "description": { "display_hint": { "type": "body" } },
    "images": {
      "content_type": "image_url",
      "display_hint": { "type": "primary_image" }
    },
    "product_url": { "content_type": "website_url" },
    "listed_at": { "content_type": "datetime", "display_hint": { "type": "timestamp" } },
    "price": { "display_hint": { "type": "money" } },
    "category": { "display_hint": { "type": "category" } },
    "internal_notes": { "content_type": "metadata", "display_hint": { "hidden": true } }
  }
}

When updating schema, send it in the schema field of the PUT /settings request body.

Reading and updating safely

The schema you send replaces the stored schema in full — fields you leave out are removed. SafetyKit may also adjust your namespace’s configuration (display labels, hidden fields, field limits), so an update built from a stale copy can silently undo those changes. Two tools prevent that:

Read before you write. GET /v1/data/{namespace}/settings returns the stored schema, settings, and a version number that increments each time the configuration is updated — by your API calls or by SafetyKit. Build your update by fetching the current schema, modifying it, and sending the whole document back.

Send previous_version. Include the version from your GET (or from your last update’s response) as previous_version in the PUT body. If the stored configuration changed since that read, the update is rejected with a 409 instead of overwriting it — GET again, re-apply your changes, and retry. We strongly recommend this for automated schema syncs; a fixed schema pushed unconditionally on every deploy will eventually overwrite configuration you didn’t know about.

settings is also replaced wholesale when provided; omit it to leave settings unchanged.

Content types

content_type describes what a field’s value is, which controls how SafetyKit processes and renders it:

Value	Meaning
image_url	Image URL(s) that SafetyKit should fetch and analyze
video_url	Video URL(s) that SafetyKit should fetch and analyze
audio_url	Audio URL(s) that SafetyKit should fetch and analyze
website_url	URL reference(s) that should be processed as web content
datetime	Date/time field
metadata	Structured context that should be stored but not indexed
markdown	Text that should render as markdown
html	Text that should render as HTML

Display hints

display_hint describes where and how a field appears in the SafetyKit UI. It takes:

• type: the field’s display role (see below)
• name: a display label to use instead of the humanized field key
• hidden: hide the field from default UI display

Supported display_hint.type roles, by category:

Category	Roles
Identity	title, subtitle, category, identifier, canonical_url, status, timestamp
Text	summary, body
Badges	primary_tag_set, tag_set
Media	profile_image, primary_image, image_set, video_set, audio_set
Structured objects	profile, message, thread, two_person_chat
Metadata	money, location, rating, attribute, attribute_group

Notes on specific roles:

• Use summary for short descriptive text and body for the main description, transcript, or message body. Combine body with content_type: "markdown" or content_type: "html" when the text needs rich rendering.
• Use primary_image for the single representative image and image_set for supporting image collections.
• Use thread for multi-participant transcripts, and two_person_chat only when a conversation has exactly two parties (it renders as left/right message bubbles).
• Identity roles (title, subtitle, identifier, status, timestamp, canonical_url) form the object header in detail views.

Fields without a display hint still render, in a default supporting-details area. Fields with display_hint.hidden: true are removed from default display.

Other field settings

• ingest_as: parse the field before indexing (float or datetime).
• belongs_to: name of the parent object namespace this field references, creating a parent-child relationship. See Multi-Namespace Orchestration.
• field_limit: maximum amount of the field to send to AI models — a character limit for text fields, or a maximum item count for array fields such as image URL lists.

Tips

• Keep field names stable within a namespace.
• Use consistent types for a field over time.
• Start with a minimal schema and expand as needed.
• When changing schema in production, roll out incrementally and monitor outputs for a full cycle before introducing additional field changes.

Quick reference and gotchas

• Use content_type: "datetime" for timestamp-like values (not timestamp, which is a display_hint.type).
• Use metadata for context fields that should be stored but not indexed.
• Use URL content types (image_url, video_url, audio_url, website_url) only for URLs you want SafetyKit to process.
• Display roles describe placement; content types describe rendering. For example, prefer display_hint.type: "body" + content_type: "markdown" over inventing a role for markdown text.
• Keep one field name mapped to one semantic type over time to avoid drift in outputs.