Records and Metadata: structured data in Sutram
Introduction
Not all knowledge is a file. Often what matters is a structured record: a document with predictable fields — title, author, date, category, number — that you want to create consistently, number automatically, and filter later.
Sutram's Records are exactly that: typed entries, with validated metadata and an automatically generated identifier (slug), instead of loose folders with free-form names. It is the difference between "a folder called Contract ACME final v2 (2).pdf" and a record CTR-2026-014 with author, date, and status filled in and checked.
When to use Records instead of loose files
Use Records when the content:
- Has fields that repeat and you want to fill them in the same way every time (contracts, reports, specifications, posts)
- Needs automatic numbering or identification with no collisions
- Will be filtered and searched by those fields (by author, category, year…)
- Should follow a standard across people and over time
For material that has no fixed structure — a one-off attachment, an image, a draft — an ordinary folder in the Content tab is enough.
Plan requirement: Records are a feature of the paid plans (starting with Pro). The schema-reading tools are available on all plans; creating categories and metadata definitions requires the feature enabled.
Core Concepts
The Records system has three layers, from the most generic to the most concrete:
1. Metadata definitions (the fields)
A metadata definition is a reusable field, with a type. It describes what a piece of data means and which values it accepts:
| Type | What for | Example |
|---|---|---|
| text | Free text | title, author |
| enum | Closed list of allowed values | category (post, docs), status (draft, approved) |
| boolean | True/false | confidential |
| date | Date | published_at |
| computed | Value derived automatically (e.g., sequential number) | document number |
Definitions are created once and reused across several categories.
2. Record categories (the mold)
A record category is the mold that says which fields a record of that type uses, which are required, in what order, and how the slug is composed. For example, a "Documentation" category may require title, category, and summary, and optionally published_at.
3. Records (the entry)
A Record is a concrete entry created from a category: a folder with metadata validated against the mold and a slug generated automatically. Because the fields are checked at creation, every record of the same category stays uniform.
Slug Generation
The slug is the record's name/identifier, assembled automatically in two steps:
- Numeric base — defined by a computed field's
computed_fromentries. It determines which values form the uniqueness key for the sequential numbering (e.g., language + area →PT-0100). - Slug composition — defined by the category's
slug_fromentries. It defines which fields (including the numeric base) make up the final slug.
This way, two records that share the same numeric base receive distinct sequential numbers (PT-0100-SWA-001, PT-0100-PPC-002), while different bases number independently. The result is a predictable, collision-free identification, with no one needing to manage counters by hand.
Records and the Wiki
Records do not live in isolation: each Record can have a mirror node in the Wiki, which brings its full text into the search and connects it to the knowledge graph through [[slug]] mentions. In other words, the structured data you organize as a Record also becomes navigable knowledge. See Wiki and Knowledge Graph.
Roles and Permissions
| Action | Owner / Admin | Member | Viewer |
|---|---|---|---|
| Read categories, metadata, and records | Yes | Yes | Yes |
| Create, edit, and delete records | Yes | Yes | No |
| Define/edit categories and metadata definitions | Yes | No | No |
Creating and editing records is open to owner, admin, and member. Schema configuration (categories and metadata definitions), however, is restricted to owner and admin. Viewers can only read.
Best Practices
- Define the schema before creating in bulk — getting the fields and the slug right first avoids rework later.
- Prefer enum over free text where the values are known — it ensures consistency and lets you filter without typos.
- Use computed fields for numbering — let Sutram handle the sequence instead of numbering manually.
- Think of the slug as an address — stable fields in
slug_fromproduce durable identifiers.
Frequently Asked Questions
Q: What is the difference between a Record and an ordinary folder?
A: An ordinary folder just has a free-form name. A Record is created from a category, with validated metadata and an automatic slug — so all records of the same type stay uniform and identifiable.
Q: Do I need programming to use Records?
A: No. You define categories and metadata and create records through the Sutram interface. The same operations are also available via the MCP Server, for automation with AI.
Q: Can I change the schema after I already have records?
A: Yes, categories and metadata definitions can evolve. Changing fields that make up the slug may recalculate the identifier of new records — plan the slug fields carefully.
Q: Who can create records?
A: Owner, admin, and member create and edit records. Only owner and admin define categories and metadata. Viewers only read.
Document Version: 1.0 Last Updated: July 2026 Author: Sutram Development Team