SolidX
ReferenceMetadata Schema

Metadata Schema

Reference for the SolidX metadata schema and how it drives runtime behavior.

Metadata Overview

Mental Model

In SolidX, metadata is the declarative layer that defines the application the platform will materialize at runtime.

  • Models and fields define data structure.
  • Views, actions, and menus define application behavior and navigation.
  • Roles, permissions, rules, templates, and settings define platform policy and runtime behavior.

Editing metadata changes full-stack platform behavior, not only isolated configuration values.

The metadata schema in SolidX defines the structure and behavior of platform components through declarative configuration rather than direct framework-level rewrites.

SolidX allows configuring both backend and frontend functionality using metadata configuration.

The metadata can either be defined in JSON files or through the admin interface. When any metadata is created or updated through the admin interface, it is stored in the database as well as in the JSON file for the corresponding module. This allows for easy version control and migration of metadata changes across different environments.

Every module needs its own metadata file, which is then seeded into the database.

Seeding Metadata

Seeding is the process that initializes the database with the metadata and platform records required for SolidX to function correctly.

Note

The result of the seeding step is a working SolidX environment, not only a populated database.

Seeding Mental Model

In SolidX, metadata in JSON is only part of the story. The platform becomes usable when that metadata is seeded into the database so the runtime can discover modules, views, roles, menus, templates, and other platform records.

  • A plain database is only persistence.
  • A seeded database is a functioning SolidX environment.
  • That is why seeding is a bootstrap step, not only sample-data insertion.

The key idea is that seeding is how declarative metadata becomes active platform state.

Why Seeding Matters

Seeding gives you a few immediate benefits:

  • Bootstraps the platform: a new database becomes a usable SolidX instance rather than an empty persistence layer.
  • Keeps environments consistent: local, test, and deployed environments can all be brought to the same metadata baseline.
  • Activates metadata changes: when metadata changes in JSON or in the platform workflow, seeding is how those changes become active in the database.
  • Reduces manual setup: key platform configuration does not need to be recreated by hand in every environment.

To apply metadata changes made in the JSON file directly, you must sync the database with the updated metadata files.

  1. Seed metadata into the database:
solidctl seed

This command reads all metadata files and updates the SolidX database.

By default, this triggers the ModuleMetadataSeederService, provided by the @solidxai/core package. It is responsible for populating the platform metadata needed by SolidX.

  1. (Only for code generation changes) Refresh the generated code:
# If your metadata changes involve code generation, prefer regenerating the module:
solidctl generate module

# If you want a smaller, targeted refresh, generate a single model:
solidctl generate model

This step ensures the generated code reflects the latest metadata. Typical cases where this extra step is required:

  • Adding a new module
  • Adding fields to a model

Tip

Just running the solidctl seed command is sufficient for most cases, except the ones mentioned above, since the platform reads the metadata directly from the database at runtime.

What Gets Seeded

Seeding does not only load modules and models. It also initializes several platform concerns that SolidX expects to exist at runtime.

  • Permissions: permission names are derived from controller and controller method names, for example UserController.findMany.
  • Media storage providers: storage backends such as default-filesystem are initialized.
  • System fields metadata: core system models and fields from the platform metadata are seeded.
  • Functional module metadata: module JSON files are read and stored in the database.
  • Roles: default roles such as Admin and Internal User are created, alongside any custom roles defined in metadata.
  • Users: default users defined in metadata are seeded.
  • Views: generated UI definitions are created from metadata.
  • Actions: view-level actions are linked into the generated experience.
  • Menus: navigation structure is initialized.
  • Email templates: default email notification templates are seeded.
  • SMS templates: SMS notification templates are seeded.
  • Settings: application-level configuration records are initialized.
  • Security rules: record-level access policies are seeded.
  • List of values: reusable enumerations and dropdown value sets are seeded.
  • Dashboards: dashboard configuration and summaries are initialized.

Operational Notes

  • If you change metadata only, seed is usually enough.
  • If your metadata change affects generated backend code, run generate module or generate model after seeding.
  • After seeding, verify seeded users and review permissions for any custom roles so the environment behaves as expected.

Key Components

Below are the key components of the metadata schema. All the functionality concerning the below components is driven by the metadata schema.

Module Metadata

The root configuration for each module, defining its identity, scope, defaults, and lifecycle.

Model Metadata

Defines the entities for each module, including table mapping, runtime flags, and data-source behavior.

Field Metadata

Specifies the individual fields for each model, including validation, persistence, relations, and computed behavior.

View Metadata

Configures how models are rendered through generated list, form, tree, card, and kanban views.

Action Metadata

Defines built-in and custom actions tied to models, routes, and generated views.

Menu Item Metadata

Configures the admin navigation structure, menu hierarchy, ordering, and action linkage.

Roles & Permissions

Defines high-level access control through roles and permission assignment.

Users

Manages seeded user accounts, default identity setup, and role binding.

Email Templates

Configures email notification templates, body references, and activation flags.

SMS Templates

Configures SMS notification templates, provider template IDs, and text-template behavior.

Media Storage Providers

Defines storage backends for media assets, including filesystem and S3-backed configurations.

Scheduled Jobs

Configures recurring background tasks, schedules, and execution classes.

Security Rules

Defines record-level access rules, role binding, and filter-based visibility behavior.

List of Values

Manages reusable enumerations and dropdown options shared across modules and views.

Dashboard Metadata

Covers dashboard configuration, widget composition, and summary-driven admin surfaces.

Best Practices

Naming Conventions

  • Use kebab-case for internal names such as fees-portal and institute-list-view.
  • Use PascalCase for display names shown in the UI such as Fees Portal and Institute List View
  • Use camelCase for field names such as instituteName and feeAmount.

Security First

  • Configure roles and permission sets early instead of widening access later.
  • Add security rules wherever role access alone is not enough to protect records.
  • Apply least-privilege access to sensitive models and workflows.

Performance Optimization

  • Add indexes deliberately for fields that are frequently searched, filtered, joined, or sorted.
  • Be deliberate about schema growth as models and generated views expand over time.

User Experience

  • Group related fields logically in generated forms and views.
  • Choose field types that match both the data shape and the authoring experience.
  • Add descriptions where they improve editor clarity or reduce configuration mistakes.

Maintainability

  • Keep field configuration patterns consistent across modules.
  • Version metadata changes carefully and review them like application code.
  • Test security-sensitive metadata after seeding so runtime behavior matches intent.

Data Integrity

  • Configure field validations deliberately rather than relying on UI behavior alone.
  • Choose stable and unique user keys that remain meaningful over time.
  • Use appropriate data types and relation cascading rules for the lifecycle of the data.

Worked Tutorials

If you want to see these metadata surfaces applied in a working build flow before reading the individual reference pages, start with one of these tutorials.

Todo App with SolidX

A smaller end-to-end example that shows how module, model, field, view, and action metadata fit together in a simple build flow.

School Fees Portal Tutorial

A larger multi-module implementation that uses metadata across onboarding, permissions, views, payment workflows, and operational configuration.

solidctl Reference

Reference for the SolidX CLI (`solidctl`) used to scaffold, build, upgrade, inspect, seed, test, generate, and run agent tasks in a SolidX project.

Modules

Overview of the module metadata schema used in SolidX.

On this page

Metadata OverviewSeeding MetadataWhy Seeding MattersWhat Gets SeededOperational NotesKey ComponentsBest PracticesWorked Tutorials