Unify ID, audit, and tenant field naming across protocol layer by Copilot · Pull Request #877 · objectstack-ai/spec

Copilot · 2026-03-05T05:12:12Z

Audit Summary:

modified_at / modified_by: ✅ Zero remaining (only in ROADMAP changelog text)
space_id: ✅ Zero remaining (only in ROADMAP changelog text)
_id (standalone): ✅ Zero remaining in protocol code. Only remaining are:
- TypeScript unused parameter convention (_id as param name) — correct
- Documentation comments explaining the rule ("MUST NOT return _id") — correct
- MongoDB foreignField: '_id' in storage-layer examples — intentionally preserved
- Standards guide text explaining not to use _id — correct

Original prompt

This section details on the original issue you should resolve

<issue_title>全仓库统一 ID 字段、系统字段及多租户字段命名规范（消除 _id / space_id / modified_xx 混用）</issue_title>
<issue_description>## 背景
现有仓库内关于主键 ID 字段、审计与租户字段命名混杂，存在 _id / id、space_id / tenant_id、modified_at/by / updated_at/by 等并存使用，违反了 SystemFieldName 统一规范，导致 driver、引擎、mock、handler、测试等层面不一致，埋下兼容和维护隐患。鉴于 audit/prompt/mock 多处已传播此问题，需统一整改。

需要合并解决的具体问题

1. ID 字段统一

ObjectQL、protocol、engine��mock、handler、test、业务类型定义等多处混用 _id 和 id。

数据驱动接口规定只返回 id，但上下游仍有 _id 查询/写入/转换逻辑。

Studio/types/action handlers/示例代码需移除 _id，统一投射 id。

2. 审计字段统一

created_at、updated_at 应作为标准，部分 audit hook 使用 modified_at/modified_by。

所有自动审计挂钩、业务代码、mock、prompt 均应重命名为 updated_at/updated_by。

3. 多租户隔离字段统一

租户字段只能用 tenant_id，ObjectQL 插件/中间件实现和协议层应全部移除 space_id。

4. Prompt 和开发者文档示例同步

包含 seed 脚本、示例、testing schema 等，应禁止 _id，只用 id。

5. Mock/插件/devPlugin

返回类型、filter、insert/update/delete、record capture 等全面清查。

6. Testing

所有相关用例和 scenario 中不再混用 _id，只出现 id。

建议修复方案（合并执行）

全文自动/人工替换 _id → id，modified_at → updated_at，space_id → tenant_id（兼容层/适配器除外）。

引擎、插件、对象协议、mock、action handler、dev-plugin、http-adapter、testing schema、prompt 全面梳理改写。

强制内部和协议文档一致，所有接口入参出参、主数据类型只出现一套规范命名。

提供一次性升级 migration/说明文档。

影响面

packages/objectql

packages/core

packages/plugins/driver-memory

examples/

apps/studio/

content/prompts/

packages/spec/

及所有 demo/test/mock/工具层

风险

第三方驱动或定制插件/适配层如因历史原因必须用 _id，需做兼容适配（如 storage column 映射）；主协议层、SDK、API 不再暴露 _id。</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes 全仓库统一 ID 字段、系统字段及多租户字段命名规范（消除 _id / space_id / modified_xx 混用） #876

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

vercel · 2026-03-05T05:12:17Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
objectstack-play	Ready	Preview, Comment	Mar 5, 2026 6:51am
spec	Ready	Preview, Comment	Mar 5, 2026 6:51am

Replace all standalone _id property keys with id across test object literals, where clauses, and assertion expectations. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Replace all standalone `_id` references with `id` across all CRM action handler files (contact, global, opportunity, case, lead). This includes type annotations, property access, destructuring, and object literals. Compound identifiers like `account_id`, `contact_id`, etc. are preserved. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ross source files Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

…, and docs Replace MongoDB-style _id field references with the platform-standard id field name in: - Mock kernels (studio, client tests) - REST, runtime, and objectql test data - QA testing schema and tests - Documentation examples and SQL snippets Compound identifiers (owner_id, account_id, tenant_id) are preserved. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

hotlong · 2026-03-05T06:43:31Z

@copilot 仔细检查所有相关代码评估是否已经完成了任务中的所有要求

…ns.mdx Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Copilot · 2026-03-05T06:48:32Z

@copilot 仔细检查所有相关代码评估是否已经完成了任务中的所有要求

Re-audited the full codebase against all 6 requirements in the issue. Found and fixed 2 remaining {_id} URL templates in content/docs/protocol/objectui/actions.mdx (commit 03a58c1).

Final audit results:

Pattern	Status	Details
`modified_at` / `modified_by`	✅ Clean	Zero remaining in code/docs
`space_id`	✅ Clean	Zero remaining in code/docs
Standalone `_id` in protocol code	✅ Clean	All 40 files fixed across objectql, core, spec, runtime, rest, client, studio, examples, docs, prompts
`_id` in storage layer (NoSQL/Mingo)	✅ Intentionally preserved	MongoDB `$group._id`, `$lookup.foreignField`, shardKey, projection — per issue guidance
`_id` as TS unused param (`_id: string`)	✅ Correct	Standard TypeScript convention for unused parameters
`_id` in doc comments ("MUST NOT return `_id`")	✅ Correct	Documenting the convention itself

All 6625 spec tests + 85 runtime + 40 rest + 134 objectql tests pass. Pre-existing failures in plugin.integration.test.ts (7) and memory-driver.test.ts (1) are unrelated to these changes.

Copilot

Pull request overview

This PR standardizes protocol-layer field naming across ObjectStack (primary key, audit fields, and tenant isolation) to eliminate mixed usage of _id/id, modified_*/updated_*, and space_id/tenant_id across runtime, ObjectQL, client tests, Studio UI, examples, and documentation.

Changes:

Replaced protocol-facing _id with id across ObjectQL protocol/engine paths, tests, Studio UI, examples, and docs.
Renamed audit and tenant fields to canonical names (updated_at, updated_by, tenant_id) in ObjectQL plugin middleware/hooks and related references.
Removed legacy _id compatibility shims/fallbacks in QA adapters, mocks, and memory matcher.

Reviewed changes

Copilot reviewed 41 out of 41 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
packages/spec/src/qa/testing.zod.ts	Update QA schema examples to reference `body.id` instead of `body._id`.
packages/spec/src/qa/testing.test.ts	Align QA tests with `body.id` capture/assertion paths.
packages/spec/src/integration/connector/database.zod.ts	Update connector example primary key naming (Mongo example changed).
packages/spec/src/data/mapping.zod.ts	Update mapping comment example to use `id`.
packages/spec/src/data/mapping.test.ts	Update mapping tests to use `id` and `fields: ['id', ...]`.
packages/spec/src/data/dataset.zod.ts	Update dataset comment to reflect `id` naming guidance.
packages/spec/docs/SYNC_ARCHITECTURE.md	Update sync example timestamp field reference.
packages/spec/DEVELOPMENT_PLAN.md	Update development plan example from `_id` to `id`.
packages/runtime/src/http-dispatcher.test.ts	Update runtime dispatcher tests to return records with `id`.
packages/rest/src/rest.test.ts	Update REST server tests to use `record.id`.
packages/plugins/driver-memory/src/memory-matcher.ts	Remove `_id`→`id` path compatibility behavior in matcher helper.
packages/objectql/src/protocol.ts	Switch protocol operations to filter/return `id` and use `updated_at`.
packages/objectql/src/protocol-data.test.ts	Update protocol data operation tests to use `id` filters/records.
packages/objectql/src/plugin.ts	Rename audit/tenant stamping and filters to `updated_*` + `tenant_id`, and use `id` filters.
packages/objectql/src/engine.ts	Use `id` for expand/query/update/delete/count paths and remove `_id` extraction.
packages/objectql/src/engine.test.ts	Update engine tests for populate/expand behavior with `id`.
packages/core/src/qa/http-adapter.ts	Remove `_id` payload fallbacks; require `id` for read/update/delete.
packages/client/src/client.msw.test.ts	Update client MSW tests to return `id` only.
packages/client/src/client.hono.test.ts	Update client Hono tests to return `id` only.
examples/app-todo/src/actions/task.handlers.ts	Update example action handlers to use `record.id` and return `{ id }`.
examples/app-crm/src/actions/handlers/opportunity.handlers.ts	Update CRM example handler to use `id` and return `{ id }`.
examples/app-crm/src/actions/handlers/lead.handlers.ts	Update CRM conversion handler to use `id` across linked records.
examples/app-crm/src/actions/handlers/global.handlers.ts	Update global handler to reference `record.id` and return `activity.id`.
examples/app-crm/src/actions/handlers/contact.handlers.ts	Update contact handlers to use `id` for updates and activity creation.
examples/app-crm/src/actions/handlers/case.handlers.ts	Update case handlers to update by `record.id`.
content/prompts/plugin/data-seed.prompt.md	Update prompt examples to use `.id` in updates/calls.
content/prompts/platform/automation.prompt.md	Update automation prompt filter examples to use `id`.
content/docs/references/qa/testing.mdx	Update docs to show capture paths using `body.id`.
content/docs/protocol/objectui/layout-dsl.mdx	Update relation comment to reference `account.id`.
content/docs/protocol/objectui/actions.mdx	Update endpoint templates from `{_id}` to `{id}`.
content/docs/protocol/objectql/types.mdx	Update ObjectQL type/storage examples to reference `id`.
content/docs/protocol/objectql/security.mdx	Update security doc examples to show `id`.
content/docs/protocol/objectql/schema.mdx	Update schema doc examples/system fields to use `id`.
content/docs/protocol/objectql/query-syntax.mdx	Update query syntax examples (joins/cursors/filters) to use `id`.
content/docs/protocol/objectql/index.mdx	Update ObjectQL index doc join example to use `id`.
content/docs/guides/standards.mdx	Update standards checklist wording related to `_id`.
apps/studio/src/types.ts	Remove `_id` from Studio `Task` type; use `id` only.
apps/studio/src/mocks/createKernel.ts	Remove `_id` fallbacks in Studio mock broker shim.
apps/studio/src/components/ObjectDataTable.tsx	Remove `_id` fallback from React keys and delete handler.
apps/studio/src/components/ObjectDataForm.tsx	Remove `_id` usage; update audit exclusion list to `updated_by`.
ROADMAP.md	Add roadmap entry documenting unified naming change.

Comments suppressed due to low confidence (2)

packages/spec/src/integration/connector/database.zod.ts:282

In the MongoDB connector example, DatabaseTableSchema.primaryKey is described as the “Actual table name in database” / “Primary key column”. For MongoDB collections the primary key field is typically _id; using primaryKey: 'id' here is misleading and may cause incorrect configs if copied. Consider reverting this example to _id, or clarifying in the schema/docs that primaryKey refers to the mapped ObjectStack field name rather than the source DB field.
content/docs/guides/standards.mdx:549
This checklist item reads like lookup field names should not end with _id, but the rest of the docs and schemas use the conventional *_id foreign-key naming (e.g. account_id) while the referenced record’s primary key is id (not _id). Please reword this to avoid suggesting that foreign key fields should be renamed away from *_id.

- [ ] Lookups don't have `_id` suffix (use `id`)
- [ ] All validations have clear messages

Initial plan

051072c

Copilot AI assigned Copilot and hotlong Mar 5, 2026

Copilot started work on behalf of hotlong March 5, 2026 05:12 View session

vercel bot deployed to Preview – objectstack-play March 5, 2026 05:12 View deployment

vercel bot deployed to Preview – spec March 5, 2026 05:15 View deployment

Copilot AI and others added 3 commits March 5, 2026 05:19

refactor: replace _id with id in engine test data and assertions

f6c0851

Replace all standalone _id property keys with id across test object literals, where clauses, and assertion expectations. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

refactor: unify _id→id, modified_at→updated_at, space_id→tenant_id ac…

fba7127

…ross source files Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

vercel bot deployed to Preview – spec March 5, 2026 05:31 View deployment

vercel bot deployed to Preview – objectstack-play March 5, 2026 05:32 View deployment

Copilot AI and others added 3 commits March 5, 2026 05:32

refactor: fix remaining _id→id in tests, mocks, and documentation

100f3a0

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

docs: add unified field naming entry to ROADMAP.md

50ecee4

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Refactor ID field naming conventions across the repository~~ Unify ID, audit, and tenant field naming across protocol layer Mar 5, 2026

Copilot finished work on behalf of hotlong March 5, 2026 05:46

vercel bot deployed to Preview – spec March 5, 2026 05:47 View deployment

vercel bot deployed to Preview – objectstack-play March 5, 2026 05:49 View deployment

Copilot started work on behalf of hotlong March 5, 2026 06:43 View session

fix(docs): replace {_id} with {id} in API endpoint templates in actio…

03a58c1

…ns.mdx Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

vercel bot deployed to Preview – objectstack-play March 5, 2026 06:48 View deployment

Copilot finished work on behalf of hotlong March 5, 2026 06:49

vercel bot deployed to Preview – spec March 5, 2026 06:51 View deployment

hotlong marked this pull request as ready for review March 5, 2026 07:35

Copilot AI review requested due to automatic review settings March 5, 2026 07:35

github-actions bot added documentation Improvements or additions to documentation protocol:data labels Mar 5, 2026

github-actions bot added tests size/m labels Mar 5, 2026

Copilot started reviewing on behalf of hotlong March 5, 2026 07:36 View session

Copilot AI reviewed Mar 5, 2026

View reviewed changes

hotlong merged commit f848d5c into main Mar 5, 2026
17 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Unify ID, audit, and tenant field naming across protocol layer#877

Unify ID, audit, and tenant field naming across protocol layer#877
hotlong merged 8 commits intomainfrom
copilot/unify-id-field-naming

Copilot AI commented Mar 5, 2026 •

edited

Loading

Uh oh!

vercel bot commented Mar 5, 2026 •

edited

Loading

Uh oh!

hotlong commented Mar 5, 2026

Uh oh!

Copilot AI commented Mar 5, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Copilot AI commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

需要合并解决的具体问题

1. ID 字段统一

2. 审计字段统一

3. 多租户隔离字段统一

4. Prompt 和开发者文档示例同步

5. Mock/插件/devPlugin

6. Testing

建议修复方案（合并执行）

影响面

风险

Comments on the Issue (you are @copilot in this section)

Uh oh!

vercel bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hotlong commented Mar 5, 2026

Uh oh!

Copilot AI commented Mar 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Mar 5, 2026 •

edited

Loading

vercel bot commented Mar 5, 2026 •

edited

Loading