Skip to content

Commit 00174f1

Browse files
hotlonghotlong
authored
Merge pull request #385 from objectstack-ai/copilot/enhance-field-protocol
2 parents 8af1a25 + be355e4 commit 00174f1

32 files changed

Lines changed: 3222 additions & 89 deletions

‎content/docs/references/data/field.mdx‎

Lines changed: 33 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ description: Field protocol schemas
1212
## TypeScript Usage
1313

1414
```typescript
15-
import { AddressSchema, CurrencyConfigSchema, CurrencyValueSchema, FieldSchema, FieldTypeSchema, FileAttachmentConfigSchema, LocationCoordinatesSchema, SelectOptionSchema, VectorConfigSchema } from '@objectstack/spec/data';
16-
import type { Address, CurrencyConfig, CurrencyValue, Field, FieldType, FileAttachmentConfig, LocationCoordinates, SelectOption, VectorConfig } from '@objectstack/spec/data';
15+
import { AddressSchema, ComputedFieldCacheSchema, CurrencyConfigSchema, CurrencyValueSchema, DataQualityRulesSchema, FieldSchema, FieldTypeSchema, FileAttachmentConfigSchema, LocationCoordinatesSchema, SelectOptionSchema, VectorConfigSchema } from '@objectstack/spec/data';
16+
import type { Address, ComputedFieldCache, CurrencyConfig, CurrencyValue, DataQualityRules, Field, FieldType, FileAttachmentConfig, LocationCoordinates, SelectOption, VectorConfig } from '@objectstack/spec/data';
1717

1818
// Validate data
1919
const result = AddressSchema.parse(data);
@@ -37,6 +37,18 @@ const result = AddressSchema.parse(data);
3737

3838
---
3939

40+
## ComputedFieldCache
41+
42+
### Properties
43+
44+
| Property | Type | Required | Description |
45+
| :--- | :--- | :--- | :--- |
46+
| **enabled** | `boolean` | ✅ | Enable caching for computed field results |
47+
| **ttl** | `number` | ✅ | Cache TTL in seconds (0 = no expiration) |
48+
| **invalidateOn** | `string[]` | ✅ | Field paths that invalidate cache (e.g., ["inventory.quantity", "pricing.base_price"]) |
49+
50+
---
51+
4052
## CurrencyConfig
4153

4254
### Properties
@@ -60,6 +72,18 @@ const result = AddressSchema.parse(data);
6072

6173
---
6274

75+
## DataQualityRules
76+
77+
### Properties
78+
79+
| Property | Type | Required | Description |
80+
| :--- | :--- | :--- | :--- |
81+
| **uniqueness** | `boolean` | optional | Enforce unique values across all records |
82+
| **completeness** | `number` | optional | Minimum ratio of non-null values (0-1, default: 0 = no requirement) |
83+
| **accuracy** | `object` | optional | Accuracy validation configuration |
84+
85+
---
86+
6387
## Field
6488

6589
### Properties
@@ -111,9 +135,15 @@ const result = AddressSchema.parse(data);
111135
| **currencyConfig** | `object` | optional | Configuration for currency field type |
112136
| **vectorConfig** | `object` | optional | Configuration for vector field type (AI/ML embeddings) |
113137
| **fileAttachmentConfig** | `object` | optional | Configuration for file and attachment field types |
138+
| **encryptionConfig** | `object` | optional | Field-level encryption configuration for sensitive data (GDPR/HIPAA/PCI-DSS) |
139+
| **maskingRule** | `object` | optional | Data masking rules for PII protection |
140+
| **auditTrail** | `boolean` | optional | Enable detailed audit trail for this field (tracks all changes with user and timestamp) |
141+
| **dependencies** | `string[]` | optional | Array of field names that this field depends on (for formulas, visibility rules, etc.) |
142+
| **cached** | `object` | optional | Caching configuration for computed/formula fields |
143+
| **dataQuality** | `object` | optional | Data quality validation and monitoring rules |
114144
| **hidden** | `boolean` | optional | Hidden from default UI |
115145
| **readonly** | `boolean` | optional | Read-only in UI |
116-
| **encryption** | `boolean` | optional | Encrypt at rest |
146+
| **encryption** | `boolean` | optional | Deprecated: Use encryptionConfig for enhanced encryption features. Simple flag for backward compatibility. |
117147
| **index** | `boolean` | optional | Create standard database index |
118148
| **externalId** | `boolean` | optional | Is external ID for upsert operations |
119149

‎content/docs/references/data/object.mdx‎

Lines changed: 75 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,25 +12,38 @@ description: Object protocol schemas
1212
## TypeScript Usage
1313

1414
```typescript
15-
import { IndexSchema, ObjectSchema, ObjectCapabilitiesSchema } from '@objectstack/spec/data';
16-
import type { Index, Object, ObjectCapabilities } from '@objectstack/spec/data';
15+
import { CDCConfigSchema, IndexSchema, ObjectSchema, ObjectCapabilitiesSchema, PartitioningConfigSchema, SoftDeleteConfigSchema, TenancyConfigSchema, VersioningConfigSchema } from '@objectstack/spec/data';
16+
import type { CDCConfig, Index, Object, ObjectCapabilities, PartitioningConfig, SoftDeleteConfig, TenancyConfig, VersioningConfig } from '@objectstack/spec/data';
1717

1818
// Validate data
19-
const result = IndexSchema.parse(data);
19+
const result = CDCConfigSchema.parse(data);
2020
```
2121

2222
---
2323

24+
## CDCConfig
25+
26+
### Properties
27+
28+
| Property | Type | Required | Description |
29+
| :--- | :--- | :--- | :--- |
30+
| **enabled** | `boolean` | ✅ | Enable Change Data Capture |
31+
| **events** | `Enum<'insert' \| 'update' \| 'delete'>[]` | ✅ | Event types to capture |
32+
| **destination** | `string` | ✅ | Destination endpoint (e.g., "kafka://topic", "webhook://url") |
33+
34+
---
35+
2436
## Index
2537

2638
### Properties
2739

2840
| Property | Type | Required | Description |
2941
| :--- | :--- | :--- | :--- |
30-
| **name** | `string` | optional | Index name |
42+
| **name** | `string` | optional | Index name (auto-generated if not provided) |
3143
| **fields** | `string[]` | ✅ | Fields included in the index |
32-
| **unique** | `boolean` | optional | Whether the index is unique |
33-
| **type** | `Enum<'btree' \| 'hash' \| 'gin' \| 'gist'>` | optional | Index type (default: btree) |
44+
| **type** | `Enum<'btree' \| 'hash' \| 'gin' \| 'gist' \| 'fulltext'>` | optional | Index algorithm type |
45+
| **unique** | `boolean` | optional | Whether the index enforces uniqueness |
46+
| **partial** | `string` | optional | Partial index condition (SQL WHERE clause for conditional indexes) |
3447

3548
---
3649

@@ -53,6 +66,11 @@ const result = IndexSchema.parse(data);
5366
| **tableName** | `string` | optional | Physical table/collection name in the target datasource |
5467
| **fields** | `Record<string, object>` | ✅ | Field definitions map |
5568
| **indexes** | `object[]` | optional | Database performance indexes |
69+
| **tenancy** | `object` | optional | Multi-tenancy configuration for SaaS applications |
70+
| **softDelete** | `object` | optional | Soft delete (trash/recycle bin) configuration |
71+
| **versioning** | `object` | optional | Record versioning and history tracking configuration |
72+
| **partitioning** | `object` | optional | Table partitioning configuration for performance |
73+
| **cdc** | `object` | optional | Change Data Capture (CDC) configuration for real-time data streaming |
5674
| **validations** | `object \| object \| object \| object \| object \| object \| object \| object \| object[]` | optional | Object-level validation rules |
5775
| **titleFormat** | `string` | optional | Title expression (e.g. "`{name}` - `{code}`"). Overrides nameField. |
5876
| **compactLayout** | `string[]` | optional | Primary fields for hover/cards/lookups |
@@ -78,3 +96,54 @@ const result = IndexSchema.parse(data);
7896
| **mru** | `boolean` | optional | Track Most Recently Used (MRU) list for users |
7997
| **clone** | `boolean` | optional | Allow record deep cloning |
8098

99+
---
100+
101+
## PartitioningConfig
102+
103+
### Properties
104+
105+
| Property | Type | Required | Description |
106+
| :--- | :--- | :--- | :--- |
107+
| **enabled** | `boolean` | ✅ | Enable table partitioning |
108+
| **strategy** | `Enum<'range' \| 'hash' \| 'list'>` | ✅ | Partitioning strategy: range (date ranges), hash (consistent hashing), list (predefined values) |
109+
| **key** | `string` | ✅ | Field name to partition by |
110+
| **interval** | `string` | optional | Partition interval for range strategy (e.g., "1 month", "1 year") |
111+
112+
---
113+
114+
## SoftDeleteConfig
115+
116+
### Properties
117+
118+
| Property | Type | Required | Description |
119+
| :--- | :--- | :--- | :--- |
120+
| **enabled** | `boolean` | ✅ | Enable soft delete (trash/recycle bin) |
121+
| **field** | `string` | optional | Field name for soft delete timestamp |
122+
| **cascadeDelete** | `boolean` | optional | Cascade soft delete to related records |
123+
124+
---
125+
126+
## TenancyConfig
127+
128+
### Properties
129+
130+
| Property | Type | Required | Description |
131+
| :--- | :--- | :--- | :--- |
132+
| **enabled** | `boolean` | ✅ | Enable multi-tenancy for this object |
133+
| **strategy** | `Enum<'shared' \| 'isolated' \| 'hybrid'>` | ✅ | Tenant isolation strategy: shared (single DB, row-level), isolated (separate DB per tenant), hybrid (mix) |
134+
| **tenantField** | `string` | optional | Field name for tenant identifier |
135+
| **crossTenantAccess** | `boolean` | optional | Allow cross-tenant data access (with explicit permission) |
136+
137+
---
138+
139+
## VersioningConfig
140+
141+
### Properties
142+
143+
| Property | Type | Required | Description |
144+
| :--- | :--- | :--- | :--- |
145+
| **enabled** | `boolean` | ✅ | Enable record versioning |
146+
| **strategy** | `Enum<'snapshot' \| 'delta' \| 'event-sourcing'>` | ✅ | Versioning strategy: snapshot (full copy), delta (changes only), event-sourcing (event log) |
147+
| **retentionDays** | `number` | optional | Number of days to retain old versions (undefined = infinite) |
148+
| **versionField** | `string` | optional | Field name for version number/timestamp |
149+

‎content/docs/references/system/driver-sql.mdx‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
title: Driver Sql
3+
description: Driver Sql protocol schemas
4+
---
5+
6+
# Driver Sql
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/system/driver-sql.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import { DataTypeMappingSchema, SQLDialectSchema, SQLDriverConfigSchema, SSLConfigSchema } from '@objectstack/spec/system';
16+
import type { DataTypeMapping, SQLDialect, SQLDriverConfig, SSLConfig } from '@objectstack/spec/system';
17+
18+
// Validate data
19+
const result = DataTypeMappingSchema.parse(data);
20+
```
21+
22+
---
23+
24+
## DataTypeMapping
25+
26+
### Properties
27+
28+
| Property | Type | Required | Description |
29+
| :--- | :--- | :--- | :--- |
30+
| **text** | `string` | ✅ | SQL type for text fields (e.g., VARCHAR, TEXT) |
31+
| **number** | `string` | ✅ | SQL type for number fields (e.g., NUMERIC, DECIMAL, INT) |
32+
| **boolean** | `string` | ✅ | SQL type for boolean fields (e.g., BOOLEAN, BIT) |
33+
| **date** | `string` | ✅ | SQL type for date fields (e.g., DATE) |
34+
| **datetime** | `string` | ✅ | SQL type for datetime fields (e.g., TIMESTAMP, DATETIME) |
35+
| **json** | `string` | optional | SQL type for JSON fields (e.g., JSON, JSONB) |
36+
| **uuid** | `string` | optional | SQL type for UUID fields (e.g., UUID, CHAR(36)) |
37+
| **binary** | `string` | optional | SQL type for binary fields (e.g., BLOB, BYTEA) |
38+
39+
---
40+
41+
## SQLDialect
42+
43+
### Allowed Values
44+
45+
* `postgresql`
46+
* `mysql`
47+
* `sqlite`
48+
* `mssql`
49+
* `oracle`
50+
* `mariadb`
51+
52+
---
53+
54+
## SQLDriverConfig
55+
56+
### Properties
57+
58+
| Property | Type | Required | Description |
59+
| :--- | :--- | :--- | :--- |
60+
| **name** | `string` | ✅ | Driver instance name |
61+
| **type** | `string` | ✅ | Driver type must be "sql" |
62+
| **capabilities** | `object` | ✅ | Driver capability flags |
63+
| **connectionString** | `string` | optional | Database connection string (driver-specific format) |
64+
| **poolConfig** | `object` | optional | Connection pool configuration |
65+
| **dialect** | `Enum<'postgresql' \| 'mysql' \| 'sqlite' \| 'mssql' \| 'oracle' \| 'mariadb'>` | ✅ | SQL database dialect |
66+
| **dataTypeMapping** | `object` | ✅ | SQL data type mapping configuration |
67+
| **ssl** | `boolean` | optional | Enable SSL/TLS connection |
68+
| **sslConfig** | `object` | optional | SSL/TLS configuration (required when ssl is true) |
69+
70+
---
71+
72+
## SSLConfig
73+
74+
### Properties
75+
76+
| Property | Type | Required | Description |
77+
| :--- | :--- | :--- | :--- |
78+
| **rejectUnauthorized** | `boolean` | optional | Reject connections with invalid certificates |
79+
| **ca** | `string` | optional | CA certificate file path or content |
80+
| **cert** | `string` | optional | Client certificate file path or content |
81+
| **key** | `string` | optional | Client private key file path or content |
82+

‎content/docs/references/system/driver.mdx‎

Lines changed: 60 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ description: Driver protocol schemas
1212
## TypeScript Usage
1313

1414
```typescript
15-
import { DriverCapabilitiesSchema, DriverInterfaceSchema, DriverOptionsSchema } from '@objectstack/spec/system';
16-
import type { DriverCapabilities, DriverInterface, DriverOptions } from '@objectstack/spec/system';
15+
import { DriverCapabilitiesSchema, DriverConfigSchema, DriverInterfaceSchema, DriverOptionsSchema, PoolConfigSchema } from '@objectstack/spec/system';
16+
import type { DriverCapabilities, DriverConfig, DriverInterface, DriverOptions, PoolConfig } from '@objectstack/spec/system';
1717

1818
// Validate data
1919
const result = DriverCapabilitiesSchema.parse(data);
@@ -27,19 +27,52 @@ const result = DriverCapabilitiesSchema.parse(data);
2727

2828
| Property | Type | Required | Description |
2929
| :--- | :--- | :--- | :--- |
30-
| **transactions** | `boolean` | ✅ | Supports transactions |
31-
| **queryFilters** | `boolean` | ✅ | Supports WHERE clause filtering |
32-
| **queryAggregations** | `boolean` | ✅ | Supports GROUP BY and aggregation functions |
33-
| **querySorting** | `boolean` | ✅ | Supports ORDER BY sorting |
34-
| **queryPagination** | `boolean` | ✅ | Supports LIMIT/OFFSET pagination |
35-
| **queryWindowFunctions** | `boolean` | ✅ | Supports window functions with OVER clause |
36-
| **querySubqueries** | `boolean` | ✅ | Supports subqueries |
37-
| **joins** | `boolean` | ✅ | Supports SQL joins |
38-
| **fullTextSearch** | `boolean` | ✅ | Supports full-text search |
39-
| **jsonFields** | `boolean` | ✅ | Supports JSON field types |
40-
| **arrayFields** | `boolean` | ✅ | Supports array field types |
30+
| **create** | `boolean` | optional | Supports CREATE operations |
31+
| **read** | `boolean` | optional | Supports READ operations |
32+
| **update** | `boolean` | optional | Supports UPDATE operations |
33+
| **delete** | `boolean` | optional | Supports DELETE operations |
34+
| **bulkCreate** | `boolean` | optional | Supports bulk CREATE operations |
35+
| **bulkUpdate** | `boolean` | optional | Supports bulk UPDATE operations |
36+
| **bulkDelete** | `boolean` | optional | Supports bulk DELETE operations |
37+
| **transactions** | `boolean` | optional | Supports ACID transactions |
38+
| **savepoints** | `boolean` | optional | Supports transaction savepoints |
39+
| **isolationLevels** | `Enum<'read-uncommitted' \| 'read-committed' \| 'repeatable-read' \| 'serializable'>[]` | optional | Supported transaction isolation levels |
40+
| **queryFilters** | `boolean` | optional | Supports WHERE clause filtering |
41+
| **queryAggregations** | `boolean` | optional | Supports GROUP BY and aggregation functions |
42+
| **querySorting** | `boolean` | optional | Supports ORDER BY sorting |
43+
| **queryPagination** | `boolean` | optional | Supports LIMIT/OFFSET pagination |
44+
| **queryWindowFunctions** | `boolean` | optional | Supports window functions with OVER clause |
45+
| **querySubqueries** | `boolean` | optional | Supports subqueries |
46+
| **queryCTE** | `boolean` | optional | Supports Common Table Expressions (WITH clause) |
47+
| **joins** | `boolean` | optional | Supports SQL joins |
48+
| **fullTextSearch** | `boolean` | optional | Supports full-text search |
49+
| **jsonQuery** | `boolean` | optional | Supports JSON field querying |
50+
| **geospatialQuery** | `boolean` | optional | Supports geospatial queries |
51+
| **streaming** | `boolean` | optional | Supports result streaming (cursors/iterators) |
52+
| **jsonFields** | `boolean` | optional | Supports JSON field types |
53+
| **arrayFields** | `boolean` | optional | Supports array field types |
4154
| **vectorSearch** | `boolean` | optional | Supports vector embeddings and similarity search |
42-
| **geoSpatial** | `boolean` | optional | Supports geospatial queries |
55+
| **geoSpatial** | `boolean` | optional | Supports geospatial queries (deprecated: use geospatialQuery) |
56+
| **schemaSync** | `boolean` | optional | Supports automatic schema synchronization |
57+
| **migrations** | `boolean` | optional | Supports database migrations |
58+
| **indexes** | `boolean` | optional | Supports index creation and management |
59+
| **connectionPooling** | `boolean` | optional | Supports connection pooling |
60+
| **preparedStatements** | `boolean` | optional | Supports prepared statements (SQL injection prevention) |
61+
| **queryCache** | `boolean` | optional | Supports query result caching |
62+
63+
---
64+
65+
## DriverConfig
66+
67+
### Properties
68+
69+
| Property | Type | Required | Description |
70+
| :--- | :--- | :--- | :--- |
71+
| **name** | `string` | ✅ | Driver instance name |
72+
| **type** | `Enum<'sql' \| 'nosql' \| 'cache' \| 'search' \| 'graph' \| 'timeseries'>` | ✅ | Driver type category |
73+
| **capabilities** | `object` | ✅ | Driver capability flags |
74+
| **connectionString** | `string` | optional | Database connection string (driver-specific format) |
75+
| **poolConfig** | `object` | optional | Connection pool configuration |
4376

4477
---
4578

@@ -67,3 +100,16 @@ const result = DriverCapabilitiesSchema.parse(data);
67100
| **traceContext** | `Record<string, string>` | optional | OpenTelemetry context or request ID |
68101
| **tenantId** | `string` | optional | Tenant Isolation identifier |
69102

103+
---
104+
105+
## PoolConfig
106+
107+
### Properties
108+
109+
| Property | Type | Required | Description |
110+
| :--- | :--- | :--- | :--- |
111+
| **min** | `number` | optional | Minimum number of connections in pool |
112+
| **max** | `number` | optional | Maximum number of connections in pool |
113+
| **idleTimeoutMillis** | `number` | optional | Time in ms before idle connection is closed |
114+
| **connectionTimeoutMillis** | `number` | optional | Time in ms to wait for available connection |
115+

‎content/docs/references/system/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ This section contains all protocol schemas for the system layer of ObjectStack.
1616
<Card href="./data-engine" title="Data Engine" description="Source: packages/spec/src/system/data-engine.zod.ts" />
1717
<Card href="./datasource" title="Datasource" description="Source: packages/spec/src/system/datasource.zod.ts" />
1818
<Card href="./driver" title="Driver" description="Source: packages/spec/src/system/driver.zod.ts" />
19+
<Card href="./driver-sql" title="Driver Sql" description="Source: packages/spec/src/system/driver-sql.zod.ts" />
1920
<Card href="./encryption" title="Encryption" description="Source: packages/spec/src/system/encryption.zod.ts" />
2021
<Card href="./events" title="Events" description="Source: packages/spec/src/system/events.zod.ts" />
2122
<Card href="./feature" title="Feature" description="Source: packages/spec/src/system/feature.zod.ts" />

‎content/docs/references/system/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
"data-engine",
1010
"datasource",
1111
"driver",
12+
"driver-sql",
1213
"encryption",
1314
"events",
1415
"feature",

0 commit comments

Comments
 (0)