[DO NOT MERGE] fix: simplified blocklist document structure - #1172
[DO NOT MERGE] fix: simplified blocklist document structure#1172aaguiarz wants to merge 2 commits into
Conversation
WalkthroughDocumentation refactoring of the blocklists guide that replaces interactive component examples (RelationshipTuplesViewer and CheckRequestViewer) with YAML-based representations and test blocks. Narrative sections and formatting updated to align with the new verification approach. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/content/modeling/blocklists.mdx`:
- Around line 114-128: The YAML examples use a list item prefix before the tests
key (e.g., "- tests:") which is invalid for the OpenFGA store format; update
each example where " - tests:" appears (search for the "tests:" YAML blocks in
this file) by removing the leading dash so "tests:" is a top-level key and keep
the nested test entries (e.g., the "- name:" entries) unchanged; apply this fix
to every repeated test example in docs/content/modeling/blocklists.mdx.
🧹 Nitpick comments (2)
docs/content/modeling/blocklists.mdx (2)
86-101: Minor: Inconsistent leading indentation in YAML snippet.The YAML block has leading 2-space indentation before each list item (
-), which is unusual for a standalone code block. This appears to be a fragment of a larger structure but may confuse readers expecting standard YAML formatting.Suggested fix to remove leading indentation
```yaml - # Becky is a member of the product team - - user: user:becky - relation: member - object: team:product +# Becky is a member of the product team +- user: user:becky + relation: member + object: team:product - # Carl is a member of the product team - - user: user:carl - relation: member - object: team:product +# Carl is a member of the product team +- user: user:carl + relation: member + object: team:product - # Members of the product team can edit the planning document - - user: team:product#member - relation: editor - object: document:planning +# Members of the product team can edit the planning document +- user: team:product#member + relation: editor + object: document:planning</details> --- `265-271`: **Test name is misleading given the assertion.** The test name "Carl can edit the 'planning' document" suggests Carl should have access, but the assertion is `editor: false`. Consider updating the test name to accurately reflect the expected outcome. <details> <summary>Suggested fix</summary> ```diff - tests: - - name: "Carl can edit the 'planning' document" + - name: "Carl cannot edit the 'planning' document" check: - user: user:carl object: document:planning assertions: editor: false
| ```yaml | ||
| - tests: | ||
| - name: "Becky can edit the 'planning' document" | ||
| check: | ||
| - user: user:becky | ||
| object: document:planning | ||
| assertions: | ||
| editor: true | ||
| - name: "Carl can edit the 'planning' document" | ||
| check: | ||
| - user: user:carl | ||
| object: document:planning | ||
| assertions: | ||
| editor: true | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
OpenFGA store test YAML format documentation
💡 Result:
OpenFGA “store test YAML” files use the Store File Format (commonly named *.fga.yaml). Official docs:
- Store File Format (full YAML schema + examples): https://openfga.dev/docs/modeling/store-file-format [1]
- Testing Models (how to write/run tests with
fga model test): https://openfga.dev/docs/modeling/testing [2] - CLI reference (commands that consume
.fga.yaml): https://github.com/openfga/cli [3]
Minimal .fga.yaml shape
Top-level keys include name, model/model_file, global tuples/tuple_file/tuple_files, and tests. Each test can add its own tuples and include check, list_objects, and/or list_users assertions. [1][2]
name: My Store Tests
model: |
model
schema 1.1
type user
type document
relations
define viewer: [user]
tuples:
- user: user:anne
relation: viewer
object: document:1
tests:
- name: can-anne-view
check:
- user: user:anne
object: document:1
assertions:
viewer: true[1][2]
🏁 Script executed:
# Read the actual file with surrounding context
cat -n docs/content/modeling/blocklists.mdx | sed -n '105,135p'Repository: openfga/openfga.dev
Length of output: 1712
🏁 Script executed:
# Search for other test YAML examples in the repository
fd -e yaml -e yml | head -20Repository: openfga/openfga.dev
Length of output: 79
🏁 Script executed:
# Search for other test YAML examples in the blocklists.mdx file
grep -n "^```yaml" docs/content/modeling/blocklists.mdx | head -10Repository: openfga/openfga.dev
Length of output: 131
🏁 Script executed:
# Look at more of the file to see if there's a pattern with tests
rg -A 15 "tests:" docs/content/modeling/blocklists.mdx | head -50Repository: openfga/openfga.dev
Length of output: 1028
Fix YAML test structure format in code examples.
The test YAML blocks use - tests: (as a list item) followed by nested test definitions. According to OpenFGA's official store file format documentation, tests: should be a top-level key, not a list item. Remove the leading - before tests::
Correct structure
tests:
- name: "Becky can edit the 'planning' document"
check:
- user: user:becky
object: document:planning
assertions:
editor: true
- name: "Carl can edit the 'planning' document"
check:
- user: user:carl
object: document:planning
assertions:
editor: trueThis pattern appears in multiple test examples throughout the file.
🤖 Prompt for AI Agents
In `@docs/content/modeling/blocklists.mdx` around lines 114 - 128, The YAML
examples use a list item prefix before the tests key (e.g., "- tests:") which is
invalid for the OpenFGA store format; update each example where " - tests:"
appears (search for the "tests:" YAML blocks in this file) by removing the
leading dash so "tests:" is a top-level key and keep the nested test entries
(e.g., the "- name:" entries) unchanged; apply this fix to every repeated test
example in docs/content/modeling/blocklists.mdx.
|
|
This PR has had no human activity for 90 days, so it has been marked This is automated backlog grooming, not a judgment on the work. What happens next, unless there is activity:
To keep it open, push a commit or leave a comment, and the clock will reset. For work that should not auto-close, such as an RFC or long-running experiment, ask a maintainer to add |
|
This PR has had no human activity for 30 days since being marked It will be closed in 30 days unless there is new activity. If the work still matters, this is the moment to say so: leave a comment, push a commit, or ask a maintainer to add If this work is no longer being pursued, no action is needed. |
curfew-marathon
added
lifecycle/closing-soon
2 participants
Description
What problem is being solved?
I find some of our documents too verbose and I'm trying a more compact approach to discuss.
The goal is to compare this
https://openfga.dev/pr-preview/pr-1172/docs/modeling/blocklists
to this
https://openfga.dev/docs/modeling/blocklists
How is it being solved?
What changes are made to solve it?
References
Review Checklist
mainSummary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.