[DO NOT MERGE] fix: simplified blocklist document structure#1172
[DO NOT MERGE] fix: simplified blocklist document structure#1172
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.
|
1 participant
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.