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 long-form text, and can be truncated when displayed
• 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": "description" } },
    "images": {
      "content_type": "image_url",
      "display_hint": { "type": "primary_image_url" }
    },
    "product_url": { "content_type": "website_url" },
    "price": { "content_type": "metadata" },
    "category": { "content_type": "metadata" }
  }
}

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

Common content types

Supported content_type values (validated in Data API runtime and surfaced in the schema editor):

• image_url: image URL(s) intended for analysis
• video_url: video URL(s) intended for analysis
• 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

Common display hints

Supported display_hint.type values (validated in Data API runtime and surfaced in the schema editor):

• title: primary row heading
• subtitle: secondary text
• description: long-form text
• primary_image_url: primary image field
• video_url: primary video field
• location: location field
• compact_text: condensed text field
• markdown: markdown-formatted content
• email.reply_to: email reply-to field
• email.body: email body field
• email.subject: email subject field
• email.body_image: image extracted from email body
• email.logo_image: email/logo image field
• email.event: email event field
• email.footer: email footer field

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.