Metadata Schema

Overview

Mental Model

In SolidX, metadata is not just configuration sitting on the side. It is the declarative layer that tells the platform what application to become.

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

So the intuition is: when you edit metadata, you are not merely tweaking settings. You are shaping the behaviour of the full stack platform.

The metadata schema in SolidX is designed to provide a flexible and extensible way to define the structure and behavior of various application components. By using a metadata-driven approach, developers can easily customize and extend the functionality of the SolidX platform without modifying the core codebase.

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 to have 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 just 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 just sample-data insertion.

So the intuition is: 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.

Seed metadata into the database:

npx @solidxai/solidctl@latest 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.

(Only for code generation changes) Refresh the generated code:

# If your metadata changes involve code generation, prefer regenerating the module:
npx @solidxai/solidctl@latest generate module

# If you want a smaller, targeted refresh, generate a single model:
npx @solidxai/solidctl@latest 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 npx @solidxai/solidctl@latest 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, and lifecycle.

Model Metadata

Defines the data structures (entities) for each module.

Field Metadata

Specifies the individual fields for each model.

View Metadata

Configures how models are displayed (List, Form, Kanban views).

Action Metadata

Defines custom actions tied to models.

Menu Item Metadata

Configures the admin menu structure.

Roles & Permissions

Defines access control rules.

Users

Manages user accounts and profiles.

Email Templates

Configures email notification templates.

SMS Templates

Configures SMS notification templates.

Media Storage Providers

Defines storage backends for media assets.

Scheduled Jobs

Configures recurring background tasks.

Security Rules

Record-level access control rules.

List of Values

Manages reusable dropdown options.

Dashboard Metadata

Configures admin dashboard widgets and analytics.

Best Practices

Naming Conventions

Use kebab-case for internal names (fees-portal, institute-list-view)
Use PascalCase for display names (Fees Portal, Institute List View)
Use camelCase for field names (instituteName, feeAmount)

Security First

Always configure roles and security rules
Use principle of least privilege
Implement proper data filtering
Enable audit tracking for sensitive operations

Performance Optimization

Use database indexes for frequently queried fields

User Experience

Group related fields logically in forms
Use appropriate field types for data validation
Provide helpful field descriptions

Maintainability

Use consistent field configurations
Version control metadata changes
Test security rules thoroughly

Data Integrity

Configure proper field validations
Use appropriate data types
Ensure unique constraints where necessary
Choose appropriate user keys for models. User keys should be unique and stable (i.e should not change over time) for a model
Use appropriate relation cascading rules

What's Coming Up

In the upcoming sections, we'll walk through practical examples that use the metadata schema and explain each attribute in detail.

These examples are based on the Fees Portal Module (a Fee Collection Module for Educational Institutions).

If you'd like to learn more about the Fees Portal module itself, you can refer to the detailed guide here: School Fees Portal Tutorial