Skip to content

Public v2 schemas

The worker-facing v2 response models live in cms_api.public.schemas.v2 (src/cms_api/public/schemas/v2.py). Every model sets model_config = ConfigDict(extra="forbid"), so any field the store adds or renames surfaces as a validation error in tests rather than silently shipping.

Why this page is narrative, not autodoc

The schemas directory is a PEP 420 namespace package (it has no __init__.py), which the runtime tolerates but the mkdocstrings static loader (griffe) will not descend into from the enclosing regular package. Rather than modify application source under src/cms_api/ (out of scope for this docs ticket), this reference is documented narratively here -- as the spec's ยง4 fallback prescribes -- and the field-to-endpoint mapping lives in Public v2 API. The other reference pages (Application, Authentication, Public store) are autodoc'd from their regular packages.

Response bodies

The five DB-backed endpoints each return one top-level envelope; every envelope ends with a meta (MetaEnvelope).

Endpoint Top-level model Composed of
GET .../settings SettingsBundle site (SiteIdentity), site_settings (SiteSettingsBlob), meta
GET .../pages/{slug} ArticlePage content (ArticleContent), author (AuthorSlice), seo (SeoBlock), breadcrumbs (NavItem[]), related (RelatedItem[]), meta
GET .../authors/{slug} AuthorProfile author (AuthorSlice), seo (SeoBlock), stats (AuthorStats), meta
GET .../lists ListResponse items (ListItem[]), next_cursor, total, meta
GET .../sitemap SitemapResponse items (SitemapEntry[]), next_cursor, total, meta

Shared envelopes

  • MetaEnvelope -- etag (always null in the body; the HTTP ETag header is authoritative), last_modified, cache_hint (CacheHint).
  • CacheHint -- ttl_seconds, swr_seconds (mirror the response cache headers).
  • SiteIdentity -- id, acronym, name, domain, default_language, tagline.

Settings models

  • SiteSettingsBlob -- the merged-per-column site_settings (default_meta_title, default_meta_description, default_og_image, default_favicon, cdn_base_url, maintenance_mode, footer_text, icon_url, contact_email, nav_limit, ads_txt, robots_txt, default_language, navigation) plus categories (CategoryLight[]), tags (TagLight[]), templates ({element_type: TemplateBlockResolved[]}), active_template (ActiveTemplate), and feature_flags (currently {}).
  • CategoryLight -- id, slug, name, sort_order.
  • TagLight -- id, slug, name.
  • TemplateBlockResolved -- html_content, settings (override > block > element-default merge).
  • ActiveTemplate -- id, slug, version.

Article / author / list / sitemap models

  • ArticleContent -- the flat content row: id, site_id, content_type, language, slug, title, description, author_id, image fields (featured_image, image, image_opt, image_sm), flags (show_in_homepage, is_featured, is_trending), content_blocks, settings, published_at, updated_at, categories[], tags[].
  • AuthorSlice -- id, slug, name, initials, image, bio.
  • SeoBlock -- seo_title, seo_description, og_title, og_description, og_image, canonical_url, noindex, schema_type, and the computed structured_data (schema.org Article / Person).
  • NavItem -- label, url (used for breadcrumbs).
  • RelatedItem -- id, slug, title, featured_image, author_name, published_at.
  • AuthorStats -- article_count, latest_published_at.
  • ListItem -- metadata-only card: id, slug, title, description, image fields, author_name, author_image, category_slug, published_at.
  • SitemapEntry -- loc, lastmod, changefreq, priority.

These models are assembled by the shared shapers in v2_common, which guarantees the SQL and memory stores emit identical shapes (see Store design).