@nocobase/plugin-ai 2.3.0-alpha.1 → 3.0.0-alpha.2

package/dist/ai/docs/nocobase/data-sources/collection-view/index.md

@@ -1,12 +1,234 @@
 ---
-pkg: "@nocobase/plugin-collection-view"
+pkg: "@nocobase/plugin-data-source-main"
+title: "Database views"
+description: "Connect an existing database view as a data source, then configure its fields and display in NocoBase. Suitable for visual management of complex query results."
+keywords: "database view,Collection View,view,NocoBase"
 ---
 
-# Database View
+# Connect a database view
 
 ## Introduction
 
-## Manual
+Connect a database view, such as a financial-report view maintained by a DBA, a filtered customer view, or an aggregated view synchronized across systems. This lets you reuse query logic that is already defined in the database.
 
+:::tip Tip
 
-![20240324145718](https://static-docs.nocobase.com/20240324145718.png)
+Only regular views in the owner scope of the main database connection account are supported; materialized views are not supported. Even when the account has query permission for views owned by others, those views do not appear in the connection list. Before connecting a view, make sure it has stable column names and field types that NocoBase can identify.
+
+:::
+
+## Connect a database view
+
+1. Open the data-source home page from the **Data sources** menu in system settings.
+2. Select the **Main** data source in the data-source list and click **Configure** to open the main database.
+3. In main database management, click **Create collection** and select **Connect to database view**.
+
+![Configure the Main data source](https://static-docs.nocobase.com/configure_main_datasource.png)
+![Connect to a database view](https://static-docs.nocobase.com/connect_view.png)
+![Configure a database view](https://static-docs.nocobase.com/connect_view_configure.png)
+
+| Setting | Description |
+| --- | --- |
+| Collection display name | The name displayed for the database view, such as `Financial report view` or `Customer statistics view`. Use a name that explains the purpose of the view. |
+| Collection name | The identifier of the database view in NocoBase, used internally by APIs, relation fields, permissions, and workflows. It is generated automatically and can be changed manually. It supports only letters, numbers, and underscores, and must begin with a letter. |
+| Database view | Select the database view to connect. NocoBase reads its field structure and query results. When editing, you can view the connected view but cannot switch to a different view. |
+| Categories | Collection categories affect only organization in Data source management; they do not change the database view itself. |
+| Description | A collection description. State who maintains the view, which data it queries, and which pages or reports use it. |
+| Use simple pagination mode | Simple pagination mode. When enabled, Table blocks skip total-record-count queries during pagination. It is suitable for large views and can reduce query load. |
+| Record unique key | The unique identifier for a record. Database views usually have no primary key, so choose a field that can uniquely locate a record. Without it, blocks might not view or edit records correctly. |
+| Source collections | The sources of database view fields. This relates view fields to fields in existing collections so that NocoBase can identify Field types and Field interfaces. |
+| Fields | Field-mapping settings. Confirm the name, title, data type, and interface type for each field in the view. |
+| Preview | Preview database view results. Before saving, confirm that field mappings and display results meet expectations. |
+| Allow add new, update and delete actions | Whether to allow create, update, and delete operations on the database view. When enabled, NocoBase provides the related page actions. Whether writes succeed still depends on whether the database view itself is writable and whether the database account has `INSERT`, `UPDATE`, and `DELETE` permissions. |
+
+:::tip Tip
+
+`Source collections` are source collections inferred from the database view. NocoBase identifies which existing collections most view fields originate from and limits the selectable **Field source** values during field mapping.
+
+The inference result helps configure a view quickly. If the view has renamed fields, calculated fields, aggregations, or complex joins, the result might be incomplete, inaccurate, or impossible to infer. Confirm it manually in **Fields**.
+
+:::
+
+### Field mapping
+
+Field mapping must be confirmed after connecting a database view. After a view is connected, NocoBase first infers the source and database type of each view field. When it can infer a source field, it automatically uses the existing field's Field type, Field interface, and Field display name. When it cannot infer a source, it provides an initial Field type based on the database type; then confirm the field type and interface manually.
+
+[Learn more about field configuration](../data-modeling/collection-fields/index.md)
+
+![Configure a view field source](https://static-docs.nocobase.com/connect_view_configure_field_source.png)
+![Configure a view field interface](https://static-docs.nocobase.com/connect_view_configure_field_interface.png)
+
+| Setting | Description |
+| --- | --- |
+| Field source | Select the existing collection and field from which the view field originates. After choosing a source, NocoBase can reuse its Field type and Field interface. |
+| Field type | When a view field has no clear source, confirm its data type manually. |
+| Field interface | Confirm how the field is displayed and entered in pages, such as Input, Number, Date, or Select. |
+| Field display name | The name displayed for the field. Use a name that business users can recognize. |
+
+For example, if a view returns `customer_name` and it comes from the **Customer name** field in the Customers collection, map it to that field. NocoBase can then reuse the original field's title, type, and interface configuration.
+
+For fields returned by aggregations or calculations, such as `count(*) as total` or `sum(amount) as amount_total`, manually select the Field type and an appropriate Field interface.
+
+:::tip Tip
+
+`Field source` comes from NocoBase's inference of the database view and indicates which existing field a view field might correspond to. When a field has a `Field source`, NocoBase preferentially reuses the source field's Field type and Field interface.
+
+When a source field cannot be inferred, or the inferred result does not match the business meaning, remove the `Field source` and select the `Field type`, `Field interface`, and `Field display name` manually.
+
+:::
+
+### Record unique key
+
+A database view requires a Record unique key. Without one, you cannot create blocks in pages or view and edit records correctly. You can select one field or a combination of fields as the unique key. Suitable Record unique key fields usually meet these conditions:
+
+- Field values are unique
+- Field values are stable and do not change due to sorting, pagination, or statistical-calculation changes
+- Fields are not empty
+- Fields are always returned by the view
+
+For a single-table view, return the original table primary key first. For a view based on multi-table joins or aggregations, retain a stable business ID in the database view or generate a stable unique field in the database.
+
+### Allow create, update, and delete actions
+
+If a database view supports writes, enable **Allow add new, update and delete actions**. NocoBase then allows create, update, and delete operations on the view in pages.
+
+Database views are better suited to query results and are treated as read-only collections by default. Enable writes only after confirming that the database view supports the corresponding write operations and that database permissions allow them.
+
+### Preview view results
+
+Before saving, use **Preview** to inspect the view query result. Check the following:
+
+- The view can be queried normally
+- Fields are complete
+- Field types and Field interfaces match the business meaning
+- A Record unique key exists and is unique
+- Unsupported field types need adjustment in the database
+
+![Preview database view results](https://static-docs.nocobase.com/connect_view_configure_preview.png)
+
+## Configure fields
+
+After creating a database view, click **Configure fields** beside the view in the collection list to open field settings. Field settings maintain the view fields, how they display in the interface, and how database view fields map to NocoBase Field types and Field interfaces.
+
+Ordinary database-view fields come from the database view. NocoBase does not add, modify, or delete actual columns in the view. In field settings, you can add only many-to-one relation fields to supplement business relations in NocoBase. A database view cannot be the target collection of a relation field, and it usually does not need a title field.
+
+[Learn more about field configuration](../data-modeling/collection-fields/index.md)
+
+![Configure fields for a database view](https://static-docs.nocobase.com/configure_view.png)
+
+### Add a relation field
+
+Database views can add only many-to-one relation fields. A many-to-one relation field maps an existing view field to a primary key or unique field in a target collection. It lets pages display related records, but does not create actual fields or foreign-key constraints in the database view.
+
+Click **Add field** to add a many-to-one relation field.
+
+[Learn more about field configuration](../data-modeling/collection-fields/index.md)
+
+![Add a database view field](https://static-docs.nocobase.com/add_view_field.png)
+![Configure a database view relation field](https://static-docs.nocobase.com/add_view_field_configure.png)
+
+| Setting | Description |
+| --- | --- |
+| Field display name | The name shown for the many-to-one relation field. Use a name that business users recognize, such as `Customer` or `Related order`. |
+| Field name | The identifier used for the many-to-one relation field in NocoBase, including APIs, permissions, and workflows. |
+| Source collection | The source collection, which is the current database view collection. It determines which collection field is selected for `Foreign key`; when adding a many-to-one relation to a database view, it normally remains the current view. |
+| Target collection | The target collection to relate to. Usually choose a real collection, such as a general collection or an external database collection; you cannot select a database view. |
+| Foreign key | The field in the current database view that stores the target-record identifier. This field must be returned reliably by the view query. |
+| Target key | The target-collection field matched by `Foreign key`, usually a primary key or unique field. |
+| Description | A field description. Record the relation meaning, data source, maintenance method, or cautions. |
+
+### Field mapping
+
+After a database view is connected, NocoBase infers its Field type from the view fields and source fields, then assigns a default Field interface. If the field source, display method, or business meaning does not meet expectations, adjust the mapping in field settings.
+
+[Learn more about field configuration](../data-modeling/collection-fields/index.md)
+
+![Edit database view field mapping](https://static-docs.nocobase.com/edit_view_field_configure.png)
+
+:::tip Tip
+
+- **Field interface** (interface type / UI type) determines how a field displays and interacts in the client, such as Input, Number, Select, or DateTime. It is the user-facing field classification
+- **Field type** (data type) determines how NocoBase identifies the field's data. For view fields without a source field, it is normally inferred from the database field type, such as `string`, `integer`, `decimal`, `boolean`, or `datetime`
+
+:::
+
+:::warning Note
+
+Changing Field source, Field type, or Field interface does not change the database view field type. It primarily affects page display, validation rules, and how NocoBase identifies the field.
+
+:::
+
+### Synchronize from database
+
+When the database-side view field structure changes, open **Configure fields** and click **Sync from database** to read the field structure again. After synchronization, NocoBase updates fields: it adds fields newly returned by the view, removes fields that no longer exist in the view, and reconfirms field types and field sources.
+
+![Synchronize view fields from database](https://static-docs.nocobase.com/edit_view_sync_from_database.png)
+![Configure view field synchronization](https://static-docs.nocobase.com/edit_view_sync_from_database_configure.png)
+
+:::warning Note
+
+Renaming a field usually appears during synchronization as deleting the old field and adding a new field. Before synchronizing, confirm whether the old field is used by pages, permissions, workflows, or external APIs, to avoid broken configuration afterwards. Recheck Field type and Field interface after synchronization.
+
+:::
+
+### Edit a field
+
+Click **Edit** beside a field to edit its configuration. Field editing is suitable for adjusting how a field displays and is used in NocoBase, such as its display name, description, validation rules, or field-specific settings.
+
+[Learn more about field configuration](../data-modeling/collection-fields/index.md)
+
+![Edit a field](https://static-docs.nocobase.com/edit_field.png)
+![Configure an edited field](https://static-docs.nocobase.com/edit_field_configure.png)
+
+:::warning Note
+
+Editing field configuration does not change the actual column name, field type, SQL expression, or index in the database view. To change the actual view structure, change the view in the database first, then use **Sync from database**.
+
+:::
+
+### Delete a field
+
+Click **Delete** beside a field to delete it. Deleting a field removes only the field stored in NocoBase; it does not delete the actual column in the database view.
+
+[Learn more about field configuration](../data-modeling/collection-fields/index.md)
+
+![Delete a field](https://static-docs.nocobase.com/delete_field.png)
+
+:::warning Note
+
+Deleting a field can affect page blocks, filters, sorting, permissions, workflows, APIs, and existing configuration. Before deleting it, confirm whether the field is still used. If the database view still returns the column, NocoBase might identify the field again when you later run **Sync from database**.
+
+:::
+
+## Edit a view
+
+The SQL definition of a database view is maintained in the database. In the collection list, click **Edit** beside a database view to adjust its metadata and runtime settings in NocoBase; this does not modify the database view. To connect another database view, create a new database view collection.
+
+![Edit a database view](https://static-docs.nocobase.com/edit_view.png)
+![Configure an edited database view](https://static-docs.nocobase.com/edit_view_configure.png)
+
+| Setting | Description |
+| --- | --- |
+| Collection display name | The name displayed for the database view. Change it to a business-friendly name, such as `Financial report view` or `Customer statistics view`. |
+| Collection name | The identifier of the database view in NocoBase. It cannot be changed when editing. |
+| Database view | The currently connected database view. It is read-only when editing and cannot be switched to a different view. |
+| Categories | Collection categories affect only organization in Data source management; they do not change the database view. |
+| Description | A collection description. Record the view maintainer, query source, pages that use it, or reporting purpose. |
+| Use simple pagination mode | When enabled, Table blocks skip total-record-count queries during pagination. It is suitable for database views with large data volumes. |
+| Record unique key | The unique identifier for locating one record. Usually select a stable, unique view field or combination of fields. |
+| Allow add new, update and delete actions | Whether to allow create, update, and delete operations. Enable it only when the database view itself supports writes and the database account has the required permissions. |
+
+:::warning Note
+
+After changing Record unique key or Allow add new, update and delete actions, recheck whether page blocks, permissions, and workflows still behave as expected.
+
+:::
+
+## Delete a view
+
+In the collection list, click **Delete** beside a database view to delete the database view collection. Deleting it removes only the connection configuration and fields stored in NocoBase; it does not delete the view in the database.
+
+Database views in the main database can also be selected and deleted in bulk. Before deleting, check whether page blocks, charts, permissions, workflows, or external APIs still use the database view collection.
+
+![Delete a database view](https://static-docs.nocobase.com/delete_view.png)
+![Confirm database view deletion](https://static-docs.nocobase.com/delete_view_second_confirmation.png)

package/dist/ai/docs/nocobase/data-sources/data-modeling/collection-fields/advanced/china-region.md

@@ -1,11 +1,128 @@
-# China Region
+---
+title: "China region"
+description: "The China region field stores Chinese administrative divisions such as provinces, cities, and districts. It supports three-level cascading selection and hierarchical display."
+keywords: "China region,province city district,administrative division field,three-level cascade,NocoBase"
+---
+
+# China region
+
+<PluginInfo name="field-china-region"></PluginInfo>
 
 ## Introduction
 
-## Field configuration
+In NocoBase, **China region** stores Chinese administrative-division information such as provinces, cities, and districts.
+
+The China region field uses the built-in `chinaRegions` administrative-division collection and a cascading selector for data entry. Users select province, city, and district in order; values display as a complete hierarchical path.
+
+For street and building-number information, use [Input](../basic/input.md) or [Textarea](../basic/textarea.md).
+
+## Use cases
+
+China region is suitable for these business scenarios:
+
+- Locations of customers, contacts, stores, and projects
+- Address basics such as registered residence, birthplace, and shipping region
+- Service areas, sales territories, and project implementation areas
+- Data that needs filtering or aggregation by province, city, and district
+
+## Create and configure
+
+On the collection's **Configure fields** page, click **Add field** and select **China region**.
+
+![](https://static-docs.nocobase.com/data-source-manager-main-NocoBase-04-29-2026_04_52_PM.png)
+
+| Setting | Description |
+| --- | --- |
+| Field interface | China region uses `chinaRegion`, which determines how the field is entered and displayed. |
+| Field display name | Use a business-friendly name such as `Region`, `Service area`, or `Shipping region`. |
+| Field name | The internal identifier used by APIs, relation fields, permissions, and workflows. It supports only letters, numbers, and underscores, and must begin with a letter. |
+| Field type | China region is normally stored as a related record or structured value, depending on field configuration. |
+| Selection level | Controls the deepest selectable level. `Province`, `City`, and `District` are supported; the default is `District`. |
+| Require the last level | When enabled, users must select the configured deepest level before submitting. Otherwise, they can complete selection at an intermediate level. |
+| Validation rules | Configure required validation and selection level as needed. |
+| Description | Record the field meaning, entry requirements, data source, or maintainer. |
+
+:::warning Note
+
+Field names are referenced by page blocks, permissions, workflows, and APIs after creation. Confirm the name before creating the field to avoid later configuration changes.
+
+:::
+
+## Field behavior
+
+| Behavior | Description |
+| --- | --- |
+| Default Field interface | `chinaRegion`. |
+| Data source | The built-in `chinaRegions` administrative-division collection. |
+| Page component | Uses a cascading selector in edit mode. |
+| Selection levels | Supports Province, City, and District. |
+| Display | Displays a `Province / City / District` path in read mode. |
+| Filtering | Supports filtering by saved region values; capabilities depend on field configuration and blocks. |
+| Multiple selection | Not supported. |
+
+## Edit configuration
+
+Click **Edit** beside the field to change its display name, description, validation rules, selection level, and whether the last level is required.
+
+For a field from a synchronized main-database table, editing usually maps the database field to a NocoBase Field type and Field interface.
+
+| Setting | Can be edited | Description |
+| --- | --- | --- |
+| Field display name | Yes | Changes the name displayed in the interface without changing the field identifier. |
+| Field name | No | The identifier normally cannot be changed after creation. |
+| Field interface | Conditional | Main-database and synchronized fields can be adjusted during mapping. |
+| Field type | Conditional | Confirm that existing values are compatible before changing it. |
+| Selection level | Yes | Changes the selectable deepest level to Province, City, or District. |
+| Require the last level | Yes | Controls whether the configured deepest level must be selected before submission. |
+| Validation rules | Yes | Adjusts required and other validation. |
+| Description | Yes | Adds maintenance information for the field. |
+
+:::warning Note
+
+China region depends on the plugin-provided `chinaRegions` collection. Enable the **China region** field plugin before using it.
+
+:::
+
+## Delete field
+
+Click **Delete** beside a China region field to delete it. You can also select multiple fields and delete them in the main data source.
+
+Deleting a China region field created in the main database usually also deletes the actual database column and its values. For a synchronized or external-data-source field, the impact depends on the data source and field origin.
+
+:::danger Warning
+
+Deleting a field can affect page blocks, forms, filters, permissions, workflows, APIs, imports and exports, and existing data. Confirm that the field is no longer referenced before deleting it.
+
+:::
+
+## Use in pages
+
+China region fields are suitable for addresses, regions, and statistical scenarios.
+
+| Scenario | Use |
+| --- | --- |
+| Form block | Select province, city, and district with a cascading selector. |
+| Details block | Display an administrative-division path. |
+| Table block | Display the region of a record. |
+| Filter block | Filter records by region. |
+| Chart block | Aggregate business data by province, city, or district. |
+
+### Edit mode
+
+China region uses a cascading selector in edit mode.
+
+![](https://static-docs.nocobase.com/%E7%9C%81%E5%B8%82%E5%8C%BA-04-29-2026_04_54_PM.png)
+
+### Read mode
+
+China region displays as a text path in read mode, for example:
 
-![20240512180305](https://static-docs.nocobase.com/20240512180305.png)
+```text
+Beijing / Municipal district / Dongcheng District
+```
 
-## Instructions
+## Related links
 
-to be added.
+- [Fields](../index.md) - Learn about field categories and mapping.
+- [Input](../basic/input.md) - Store detailed street addresses.
+- [Textarea](../basic/textarea.md) - Store longer address descriptions.

package/dist/ai/docs/nocobase/data-sources/data-modeling/collection-fields/advanced/collection-select.md

@@ -1,11 +1,112 @@
-# Collection selector
+---
+title: "Collection select"
+description: "The Collection select field selects one or more NocoBase collections."
+keywords: "Collection select,collectionSelect,field,Field interface,NocoBase"
+---
+
+# Collection select
 
 ## Introduction
 
-## Field configuration
+In NocoBase, **Collection select** selects one or more collections.
+
+It is suitable for plugin configuration, rule configuration, and metadata management. It stores collection identifiers rather than business records. To select records from a collection, use a relation field instead.
+
+## Use cases
+
+Collection select fields are suitable for these business scenarios:
+
+- Selecting target collections in plugin configuration
+- Specifying collection scope in rule configuration
+- Metadata management and template configuration
+- Feature configuration that references collection identifiers
+
+## Create and configure
+
+On the collection's **Configure fields** page, click **Add field** and select **Collection select** to create this field.
+
+![Configure a Collection select field](https://static-docs.nocobase.com/20240512174047.png)
+
+| Setting | Description |
+| --- | --- |
+| Field interface | The field interface. Collection select uses `collectionSelect`, which determines how the field is entered and displayed in pages. |
+| Field display name | The name displayed for the field, such as `Target collection`, `Affected collection`, or `Data scope`. Use a name that business users can recognize. |
+| Field name | The field identifier used internally by APIs, relation fields, permissions, and workflows. It usually cannot be changed after creation. It supports only letters, numbers, and underscores, and must begin with a letter. |
+| Field type | The data-layer type. Collection select uses `string` by default. |
+| Default value | The default value. When a new record has no value, NocoBase can fill this value automatically. |
+| Validation rules | Validation rules. Supports base validation such as required and selection range. |
+| Description | A field description. Record the field meaning, entry requirements, data source, or maintainer. |
+
+:::warning Note
+
+Field names are referenced by page blocks, permissions, workflows, and APIs after creation. Confirm the name before creating the field to avoid later configuration changes.
+
+:::
+
+## Field behavior
+
+The default behavior of a Collection select field is as follows:
+
+| Behavior | Description |
+| --- | --- |
+| Default Field interface | `collectionSelect`. |
+| Default Field type | `string`. |
+| Available Field types | `string`, `json`. |
+| Page component | Uses a collection-selector component in edit mode. |
+| Filtering | It is usually not used as a business filter field. |
+| Sorting | It is usually not used for sorting. |
+| Validation | Supports base validation such as required and selection range. |
+
+## Edit configuration
+
+After creation, click **Edit** beside the field to edit its configuration. Edit fields to adjust how they are displayed and used in NocoBase, such as the display name, description, default value, validation rules, or field-specific settings.
+
+When a field comes from a synchronized main-database table, editing usually maps the database field to a NocoBase Field type and Field interface.
+
+| Setting | Can be edited | Description |
+| --- | --- | --- |
+| Field display name | Yes | Changes the name displayed in the interface without changing the field identifier. |
+| Field name | No | The field identifier normally cannot be changed in the edit form after creation. |
+| Field interface | Conditional | Main-database fields and synchronized fields can be adjusted during field mapping. Changes affect page input, display, and validation. |
+| Field type | Conditional | Main-database fields and synchronized fields can be adjusted during field mapping. Confirm that existing values can be used by the new type first. |
+| Default value | Yes | Adjusts the default value for new records. |
+| Validation rules | Yes | Adjusts field validation rules. |
+| Description | Yes | Adds the field meaning, entry requirements, data source, or maintainer. |
+
+:::warning Note
+
+Changing a Field type or Field interface is more than changing a display name. It affects field storage, input components, validation rules, filters, and workflow-variable usage. When the field contains substantial existing data, confirm that its data format is compatible first.
+
+:::
+
+## Delete field
+
+Click **Delete** beside a Collection select field to delete it. You can also select multiple fields and delete them in the main data source.
+
+Deleting a Collection select field created in the main database usually also deletes the actual database column and its values. For a synchronized or external-data-source field, the impact depends on the corresponding data source and field origin.
+
+:::danger Warning
+
+Deleting a field can affect page blocks, forms, filters, permissions, workflows, APIs, imports and exports, and existing data. Confirm that the field is no longer referenced by business configuration before deleting it.
+
+:::
+
+## Use in pages
+
+Collection select fields are suitable for configuration forms.
+
+
 
 
-![20240512174047](https://static-docs.nocobase.com/20240512174047.png)
+| Scenario | Use |
+| --- | --- |
+| Form block | Select one or more collections. |
+| Details block | Display selected collections. |
+| Plugin configuration | Specify the collections affected by a feature. |
+| Workflows and rules | Use collection metadata in logic. |
 
+## Related links
 
-## Example
+- [Fields](../index.md) - Learn about field categories and mapping.
+- [General collection](../../../data-source-main/general-collection.md) - Create and manage fields in a collection.
+- [Relation fields](../associations/index.md) - Select records from a collection.

package/dist/ai/docs/nocobase/data-sources/data-modeling/collection-fields/advanced/json.md

@@ -1,13 +1,111 @@
+---
+title: "JSON"
+description: "The JSON field stores structured or semi-structured data such as configuration objects and API-response fragments."
+keywords: "JSON,json,field,Field interface,NocoBase"
+---
+
 # JSON
 
 ## Introduction
 
-## Field configuration
+In NocoBase, the **JSON** field stores structured or semi-structured data.
+
+It is suitable for external API response fragments, extended configuration, dynamic attributes, and other data with an unstable structure. It is flexible, but harder to filter, validate, and display than ordinary fields. When the structure is stable, split it into explicit fields first.
+
+## Use cases
+
+JSON fields are suitable for these business scenarios:
+
+- Raw external API responses
+- Dynamic extended attributes
+- Complex configuration objects
+- Temporary data that cannot yet be split into structured fields
+
+## Create and configure
+
+On the collection's **Configure fields** page, click **Add field** and select **JSON** to create this field.
+
+![Configure a JSON field](https://static-docs.nocobase.com/20240512173905.png)
+
+| Setting | Description |
+| --- | --- |
+| Field interface | The field interface. JSON uses `json`, which determines how the field is entered and displayed in pages. |
+| Field display name | The name displayed for the field, such as `Extended information`, `API response`, or `Configuration`. Use a name that business users can recognize. |
+| Field name | The field identifier used internally by APIs, relation fields, permissions, and workflows. It usually cannot be changed after creation. It supports only letters, numbers, and underscores, and must begin with a letter. |
+| Field type | The data-layer type. JSON uses `json` by default. |
+| Default value | The default value. When a new record has no value, NocoBase can fill this value automatically. |
+| Validation rules | Validation rules. Supports valid-JSON and required validation. |
+| Description | A field description. Record the field meaning, entry requirements, data source, or maintainer. |
+
+:::warning Note
+
+Field names are referenced by page blocks, permissions, workflows, and APIs after creation. Confirm the name before creating the field to avoid later configuration changes.
+
+:::
+
+## Field behavior
+
+The default behavior of a JSON field is as follows:
+
+| Behavior | Description |
+| --- | --- |
+| Default Field interface | `json`. |
+| Default Field type | `json`. |
+| Available Field types | `json`, `jsonb`. |
+| Page component | Uses a JSON editor or text-input component in edit mode. |
+| Filtering | Filtering depends on the database and field mapping; it is usually not a primary filter field. |
+| Sorting | It is usually not used for sorting. |
+| Validation | Supports valid-JSON and required validation. |
+
+## Edit configuration
+
+After creation, click **Edit** beside the field to edit its configuration. Edit fields to adjust how they are displayed and used in NocoBase, such as the display name, description, default value, validation rules, or field-specific settings.
+
+When a field comes from a synchronized main-database table, editing usually maps the database field to a NocoBase Field type and Field interface.
+
+| Setting | Can be edited | Description |
+| --- | --- | --- |
+| Field display name | Yes | Changes the name displayed in the interface without changing the field identifier. |
+| Field name | No | The field identifier normally cannot be changed in the edit form after creation. |
+| Field interface | Conditional | Main-database fields and synchronized fields can be adjusted during field mapping. Changes affect page input, display, and validation. |
+| Field type | Conditional | Main-database fields and synchronized fields can be adjusted during field mapping. Confirm that existing values can be used by the new type first. |
+| Default value | Yes | Adjusts the default value for new records. |
+| Validation rules | Yes | Adjusts field validation rules. |
+| Description | Yes | Adds the field meaning, entry requirements, data source, or maintainer. |
+
+:::warning Note
+
+Changing a Field type or Field interface is more than changing a display name. It affects field storage, input components, validation rules, filters, and workflow-variable usage. When the field contains substantial existing data, confirm that its data format is compatible first.
+
+:::
+
+## Delete field
+
+Click **Delete** beside a JSON field to delete it. You can also select multiple fields and delete them in the main data source.
+
+Deleting a JSON field created in the main database usually also deletes the actual database column and its values. For a synchronized or external-data-source field, the impact depends on the corresponding data source and field origin.
+
+:::danger Warning
+
+Deleting a field can affect page blocks, forms, filters, permissions, workflows, APIs, imports and exports, and existing data. Confirm that the field is no longer referenced by business configuration before deleting it.
+
+:::
+
+## Use in pages
+
+JSON fields are suitable for integration and extended-configuration scenarios.
 
+![Use a JSON field in a page](https://static-docs.nocobase.com/20260710151854.png)
 
-![20240512173905](https://static-docs.nocobase.com/20240512173905.png)
 
+| Scenario | Use |
+| --- | --- |
+| Form block | Enter or edit JSON data. |
+| Details block | Display structured content. |
+| Workflows | Store or read external API response fragments. |
+| APIs | Pass or return extended objects. |
 
-## Example
+## Related links
 
-To be added.
+- [Fields](../index.md) - Learn about field categories and mapping.
+- [General collection](../../../data-source-main/general-collection.md) - Create and manage fields in a collection.