doc: field-level policy

[ymc9]

Summary by CodeRabbit

• Documentation
  • Added comprehensive field-level access control policy documentation with usage examples and behavior specifications.
  • Included detailed explanations of read and update operation constraints and behaviors.
  • Updated roadmap to reflect field-level access control as a completed feature.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[vercel]

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

Project	Deployment	Review	Updated (UTC)
zenstack-new-site	Ready	Preview, Comment	Jan 7, 2026 10:13am

[coderabbitai]

Walkthrough

This PR documents field-level access control policies in ORM documentation, including usage examples with @allow and @deny decorators, constraints, read/update behavior, and error handling. The roadmap is updated to mark field-level access control as completed.

Changes

Cohort / File(s)	Summary
Field-Level Policy Documentation docs/orm/access-control/field-level.md	Replaces placeholder heading with comprehensive feature documentation including: imports for AvailableSince and PreviewFeature components, usage examples with @allow/@deny decorators on fields, constraints (read/update only, no relation/computed fields), read behavior with SQL-style null representation, caveat on NULL ambiguity, and update behavior with ORMError rejection details. Samples section marked as "Coming soon!".
Roadmap Update docs/roadmap.md	Marks field-level access control feature as completed by checking the corresponding roadmap entry checkbox.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• doc: update roadmap #496: Updates the roadmap to mark field-level access control policies as completed, directly overlapping with this PR's roadmap changes.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'doc: field-level policy' directly aligns with the main changes, which document field-level access control policies including read/update behavior and constraints.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

docs/orm/access-control/field-level.md (2)

34-34: Fix subject-verb agreement in sentence.

Line 34 contains a grammatical error: "fields that violates" should be "fields that violate."

Suggested fix

-When reading a row, fields that violates "read" policies will be nullified in the result. Conceptually, the following form of SQL is generated to guard the fields:
+When reading a row, fields that violate "read" policies will be nullified in the result. Conceptually, the following form of SQL is generated to guard the fields:

---

48-48: Improve clarity of phrasing in the caveat explanation.

Line 48 reads awkwardly: "Setting unreadable fields null" lacks a preposition. Consider: "Setting unreadable fields to null."

Suggested fix

-Setting unreadable fields null brings a caveat that you cannot tell whether a field is actually `NULL` in the database or just unreadable due to access control. So why don't we instead omit the fields from the result?
+Setting unreadable fields to null brings a caveat that you cannot tell whether a field is actually `NULL` in the database or just unreadable due to access control. So why don't we instead omit the fields from the result?

📜 Review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a2475ef and a7dbe6e.

📒 Files selected for processing (2)

• docs/orm/access-control/field-level.md
• docs/roadmap.md

🔇 Additional comments (2)

docs/orm/access-control/field-level.md (1)

5-60: Strong documentation for field-level access control policies.

The documentation provides a clear, well-structured introduction to field-level policies. The code example effectively illustrates the feature, and the sections covering constraints, read behavior, update behavior, and caveats comprehensively explain the key concepts. The SQL conceptual representation helps readers understand the underlying mechanism, and the caveat section addresses an important design decision. The roadmap and Samples placeholders set appropriate expectations for readers.

docs/roadmap.md (1)

16-16: Roadmap status update is accurate.

The status change for "Field-level access control" from uncompleted to completed aligns with the comprehensive documentation added in the corresponding file.