Collections and globals

Collections hold many documents—posts, products, people, media. Globals hold exactly one logical document—site settings, navigation, or a home-page composition. Both use the same fields, access, validation, hooks, localization, and field redaction.

ridu.Collection and ridu.Global are typed Go config values. Their serializable shape becomes generated Go and TypeScript contracts, OpenAPI, and the admin model.

Define a collection

A collection slug is its durable public address in REST, generated clients, relationships, and the admin. Presentation belongs in Labels and Admin; runtime behaviour belongs in fields, access, hooks, and explicit capabilities.

package content

import (
  "github.com/riducms/ridu"
  "github.com/riducms/ridu/field"
)

var Articles = ridu.Collection{
  Slug: "articles",
  Labels: ridu.CollectionLabels{
    Singular: "Article",
    Plural:   "Articles",
  },
  Admin: ridu.CollectionAdmin{
    UseAsTitle:     "title",
    DefaultColumns: []string{"title", "category", "summary"},
    Group:          "Editorial",
    Description:    "Long-form stories published on the site.",
  },
  Fields: []field.Definition{
    field.Text("title", field.Required()),
    field.Textarea("summary"),
    field.Relationship("category", field.To("categories")),
    field.Group("seo", field.Fields(
      field.Text("slug", field.Required()),
    )),
  },
  Indexes: []ridu.CollectionIndex{
    {Fields: []string{"category", "seo.slug"}, Unique: true},
  },
}

Register the value in ridu.Config.Collections. Config resolution rejects unknown relationship targets, invalid admin fields, duplicate slugs, and unsupported index paths.

Collection configuration map

See Fields for every builder and option. A field’s name is part of stored and generated contracts; its label and description affect presentation only.

Admin metadata is presentation

CollectionAdmin configures browsing and editing without changing API authorization:

UseAsTitle, columns, folder, and parent fields must name existing direct fields. Folder relationships may target another collection; a parent relationship must target the collection itself. Live-preview URL templates accept {id}, {collection}, and {field:path.to.value} placeholders. Read Admin and Editorial workflows for the authoring experience.

Compound indexes

Use CollectionIndex when the tuple, rather than one field, is indexed or unique:

Indexes: []ridu.CollectionIndex{
  {Fields: []string{"tenant", "seo.slug"}},
  {Fields: []string{"tenant", "externalID"}, Unique: true},
},

An index contains 2–32 unique, ordered paths. Paths can pass through non-repeated groups and end at a supported scalar or a singular, non-polymorphic relationship/upload reference. Arrays, blocks, rich text, objects, has-many references, and polymorphic references are not index terminals.

Official stores use PostgreSQL-style NULLS DISTINCT semantics: a unique tuple can appear more than once when any component is null or absent. Localized values are unique per exact locale, not across a fallback result. Trashed documents leave the active unique set; restoring one can fail with conflict if another active document has claimed its tuple.

Opt-in capabilities

A collection supports create, duplicate, find, list, update, delete, filtering, pagination, selection, population, access evaluation, hooks, and generated contracts. Flags add features:

All three official database adapters supply these store capabilities; MongoDB does so inside its bounded production profile. Application construction fails if an adapter cannot support an enabled feature. Continue with Authentication, Uploads, Drafts and versions, and Editorial workflows for each feature.

Access, hooks, and computed output

CollectionAccess has independent Admin, Create, Read, ReadVersions, Update, Publish, Unpublish, Delete, and Unlock rules. A nil ReadVersions rule falls back to Read; nil Publish, Unpublish, and Unlock rules fall back to Update. Read and mutation rules can return ridu.Where(...), which the store must combine atomically with the caller’s filter.

FieldAccess and FieldHooks maps use authored paths such as seo.slug. Repeated field occurrences also receive a concrete runtime path. Computed values are response-only and can be limited with local API output selection. Learn the order and transaction boundaries in Access control and Hooks.

Globals

Globals use singleton routes and generated singleton handles. Reading a global before its first write returns a schema-shaped value with defaults; the first update persists the row under the global slug.

package content

import (
  "github.com/riducms/ridu"
  "github.com/riducms/ridu/field"
)

var SiteSettings = ridu.Global{
  Slug:  "site-settings",
  Label: "Site settings",
  Admin: ridu.GlobalAdmin{
    Group:       "Settings",
    Description: "Site-wide identity and support details.",
  },
  Fields: []field.Definition{
    field.Text("siteName", field.Required()),
    field.Email("supportEmail"),
  },
  Access: ridu.GlobalAccess{
    Read:   publicRead,
    Update: administratorsOnly,
  },
}

Register it in ridu.Config.Globals. A global has no collection-style create, duplicate, list, delete/trash, auth, upload, document-lock, folder, hierarchy, or compound-index configuration. Its supported surface is smaller:

For a missing singleton, a filtered GlobalAccess.Update decision cannot match a row; the first update therefore requires an unconditional Allow. Once persisted, filtered read/update/version decisions are applied atomically to the row or each snapshot.

Renames and migrations

Rename the authored slug or field name, regenerate, then run ridu migrate create. PostgreSQL migration creation presents compatible remove/add pairs for confirmation and records accepted continuity in the immutable artifact. SQLite requires a named compiled transform to rewrite stored canonical JSON. Do not maintain hand-authored public schema IDs or edit generated manifests to force a rename.

This changes the public field from title to headline; the migration must preserve the stored value:

Fields: []field.Definition{
  field.Text("title", field.Required()),
  field.Text("headline", field.Required()),
},

Review the resulting storage and API change—especially relationships, indexes, auth identities, localized fields, and removed capabilities—before applying it. See PostgreSQL migrations, SQLite, and Generated contracts.