Concepts

This is a list of concepts that are important to understand when working with the website.

Schema

A schema is a blueprint for the data that will be stored in the CMS. It defines the structure of the data, including the types of data that can be stored and the relationships between different types of data.

A Schema is a JSON object that includes the following fields:

• name (*): The name of the schema. This is used to identify the schema in the CMS and must be unique.
• namespace (*): The namespace of the schema. This is used to create database tables and API endpoints.
• label_field (*): The field that will be used as the label for items in the CMS. This is typically a human-readable field like a title or name.
• disable_timestamp: A boolean value that determines whether the schema should include timestamp fields like created_at and updated_at.
• is_system_schema: A boolean value that determines whether the schema is a system schema. A System schema is a schema that come built-in with the CMS or a schema that was created from a Go struct. A system schema can only be extended and cannot be deleted.
• db: The database configuration for the schema. Currently, it support adding indexes and unique constraints to the schema.
• fields (*): An array of field objects that define the fields that will be stored for each item in the CMS.

Field

A field is a single piece of data that is stored for each item in the CMS. Fields can be of different types, such as text, number, date, or relationship. Each field has a name, type, and other properties that define how the data should be stored and displayed.

type (*)

The type of the field. This can be one of the following values:

• bool: A boolean value that can be true or false.
• time: A time value that includes both date and time.
• json: A JSON object that can store any type of data.
• uuid: A unique identifier that is generated automatically.
• bytes: A byte array that can store binary data.
• enum: An enumeration of values that can be selected from a list. Enum fields have an additional property called enums that defines the possible values for the field.
• string: A string value that can store short text.
• text: A text value that can store long text.
• int: An integer value.
• int8: A 8-bit integer value.
• int16: A 16-bit integer value.
• int32: A 32-bit integer value.
• int64: A 64-bit integer value.
• uint: An unsigned integer value.
• uint8: A 8-bit unsigned integer value.
• uint16: A 16-bit unsigned integer value.
• uint32: A 32-bit unsigned integer value.
• uint64: A 64-bit unsigned integer value.
• float32: A 32-bit floating point value.
• float64: A 64-bit floating point value.
• relation: A relationship to another schema. Relation fields have an additional property called relation that defines the relationship between the field and another schema.
• file: A special type of relation field that represents a file upload that alway has a relationship to the file schema.

name (*)

The name of the field. This is used to identify the field in the CMS and must be unique within the schema.

label (*)

The label of the field. This is used to display the field in the CMS and should be a human-readable name.

multiple

A boolean value that determines whether the field can store multiple values. Currently, it only take effect in file field.

size

The size of the field. This is used to determine the maximum length of the field and is used to define the size of the field in the database.

unique

A boolean value that determines whether the field should be unique. If a field is unique, each value in the field must be unique within the schema.

optional

A boolean value that determines whether the field is optional. If a field is optional, it can be null.

default

The default value of the field. This is used to set a default value for the field if no value is provided.

There are some special default values that can be used for specific field types:

• NOW(): The current date and time.
• time in RFC3339: Will be parsed to the time.Time value.

sortable

A boolean value that determines whether the field can be used to sort items in the CMS.

filterable

A boolean value that determines whether the field can be used to search for items in the CMS.

optional

A boolean value that determines whether the field is optional. If the relationship is optional, the field can be null.

is_system_field

A boolean value that determines whether the field is a system field.

A system field is a field that was created from Go code.

A field that was created by user from the Admin or JSON file is not a system field.

A system field can only be extended and cannot be deleted.

is_locked

A boolean value that determines whether the field is locked.

A locked field cannot be modified through the API and can only be modified by the Go code.

renderer

Is used to determine the field renderer in the frontend for the field.

renderer accept an object that has the following properties: - class: The class name of the field renderer. - settings: a key-value object that hold the settings for the field renderer.

enums

Use for enum field. It accept an array of object that represent the possible values for the field. Each object has the following properties:

• value: The value of the enum.
• label: The label of the enum.

relation

Use for relation field. It accept an object that represent the relationship between the field and another schema. It has the following properties:

• schema: The name of the schema that the field is related to.

• field: The name of the field in the related schema that the field is related to.

• type: The type of the relationship. This can be one of the following values:

  • o2o: A one-to-one relationship where each item in the schema is related to one item in the related schema.
  • o2m: A one-to-many relationship where each item in the schema is related to multiple items in the related schema.
  • m2m: A many-to-many relationship where multiple items in the schema are related to multiple items in the related schema.

• owner: A boolean value that determines whether the field is the owner of the relationship, only take effect in o2m and o2o relationship.

  The schema that hold the foreign key will have owner=false

  For example, field post.category that is o2m relationship to category.posts field.

  The post schema will has a foreign key to the category schema: category_id, so the field category.posts will be the owner of the relationship and category.posts will have owner=true.

• fk_columns: Use to override the default foreign key column name. By default, the foreign key column name is the name of the related schema with _id suffix.

  For example: field post.category that is o2m relationship to category.posts field. The default foreign key column name is category_id, but you can override it to cat_id by setting fk_columns to {"target_column": "cat_id"}.

db

The database configuration for the field. It accept an object that has the following properties:

• attr: A string that represent the field attributes in the database.
• collation: A string that represent the collation of the field in the database: utf8mb4_unicode_ci, utf8mb4_general_ci,...
• increment: A boolean value that determines whether the field is auto-incremented.
• key: A string that represent the key of the field in the database: PRI, UNI or MUL.

setter

The setter expression for the field. It is used to set the value of the field before saving it to the database.

getter

The getter expression for the field. It is used to get the value of the field before returning it to the client.

Resource

In FastSchema, a Resource is a component that processes user requests and returns responses. It functions similarly to a controller in the MVC pattern or a resolver in GraphQL.

Resources can be grouped, which is useful for organizing related endpoints. For example, you might group all user-related resources together.

Each Resource must have a handler, a function that processes the user request and returns the response.

When defining a Resource, you can specify the input data that it expects and the output data that it returns. This is useful for documenting the API and for validating the input and output data.

Client requests don't go directly to the Resource. Instead, they are routed by a resolver, which directs the request to the appropriate Resource. Currently, FastSchema uses a RestfulResolver, which routes requests based on the HTTP method and path. In the future, additional resolvers, such as a GraphQL resolver, may be introduced.

For more information, refer to the Resource Documentation.