Create a directory data model that survives growth
A practical record model for consistent public listings, reliable imports, searchable values, governance, and future migrations.
The practical answer first
A durable directory data model gives every listing a stable identity, one shared schema, controlled comparison values, flat categories, explicit publication state, source and review metadata, validation rules, and standard import and export representations. Separate canonical data from display choices so redesigns do not require data reinvention.
For operators, developers, and content teams defining listing fields or cleaning multiple sources before an import.
Use this template to document field names, types, rules, public surfaces, ownership, and migration behavior before collecting or transforming records.
Separate identity from presentation
Give each listing a stable internal identifier and unique public slug, while treating the display name and visual order as editable content. Define duplicate matching signals and merge ownership. URLs should remain stable where possible even when titles or categories change.
- Do not use display names as the only identity.
- Define slug collision and redirect behavior.
- Record merge and deletion decisions.
Define the shared field dictionary
For every field, record key, label, type, required status, allowed values, validation, default, searchable status, card visibility, detail visibility, submission visibility, source authority, and privacy classification. Keep one schema across listings; split the model when record types need fundamentally different decisions.
- Use controlled selects for critical comparisons.
- Keep long text out of cards by default.
- Make URL and numeric validation explicit.
Model categories and lifecycle
Use a maintainable flat category set with canonical keys and audience-facing labels. Represent draft and published item state plus submission review state separately. Define approved and rejected outcomes, featured status, source review, correction, and retirement without overloading a single status field.
- Separate payment state from editorial decision.
- Avoid nested facets the interface cannot support.
- Specify what appears in sitemap and search.
Version imports, exports, and migrations
Publish a stable CSV header set, data dictionary, encoding rules, and row-level validation. Export canonical fields and custom values in a reusable form before destructive changes. Record schema version and transformation decisions so future sources and platforms can understand the dataset.
- Test round trips with representative records.
- Preserve unknown or invalid input for review, not publication.
- Do not imply JSON portability unless the product supports it.
Directory entity model
Use these groups as a starting schema and add a field dictionary row for every custom value the directory needs.
- 01Identity
id; slug; name; canonical_source_url; duplicate_keys; created_at; updated_at; source; source_record_id.
- 02Content
short_description; full_description; website_url; image_url_and_rights; category_keys; custom_values.
- 03Lifecycle
item_status; review_status; reviewed_by; reviewed_at; review_note; featured; retired_at; reason.
- 04Governance
field_authority; permission_note; privacy_class; last_checked_at; correction_owner; audit_reference.
- 05Delivery
card_fields; detail_fields; submission_fields; searchable_fields; sitemap_rule; export_columns.
Frequently asked questions
How many custom fields should a directory have?
Use the minimum set needed for reliable decisions and operations. Directoryz supports up to 20 directory-wide custom fields, but the practical optimum depends on source quality and maintenance capacity.
Should every listing type share one schema?
Yes when visitors evaluate them with the same criteria. When fields, actions, and governance diverge materially, separate collections or models are usually clearer than a sparse union schema.
How should custom fields be named?
Use stable machine keys and clear audience-facing labels. Avoid embedding temporary campaign or layout language in canonical keys, and document type, validation, source, and public surfaces.