docs: Add comprehensive store file format documentation #518
Conversation
WalkthroughA new documentation file, Changes
Sequence Diagram(s)No sequence diagram generated as the changes are limited to documentation and do not affect control flow or feature logic. Assessment against linked issues
Assessment against linked issues: Out-of-scope changesNo out-of-scope changes found. Poem
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
docs/STORE_FILE.md (1)
1-385: Comprehensive and well-structured documentation
The newSTORE_FILE.mdprovides a thorough, organized overview of the OpenFGA store file format, covering structure, CLI usage, examples, and best practices. It aligns well with the CLI commands and user workflows.
A few optional refinements to polish the docs:
- Consistent context field naming – examples alternate between
timestampandcurrent_time. Consider standardizing on one key.- In section headings (“The store file uses YAML syntax and supports the following top-level properties”), add “the” before “following” for grammatical flow.
- Under Tests (line 126), note that each test must include at least one of
check,list_objects, orlist_users.- Capitalize “YAML” in inline notes (e.g., “Must be in YAML format”).
- In CLI examples, clarify parameter descriptions to refer consistently to store files (e.g., “Path to the store file”).
🧰 Tools
🪛 LanguageTool
[uncategorized] ~155-~155: Possible missing preposition found.
Context: ...ner: false#### List Objects Tests Validate which objects a user can access:ya...(AI_HYDRA_LEO_MISSING_TO)
[duplication] ~247-~247: Possible typo: you repeated a word.
Context: ...I Commands Using Store Files ### Store Import Import a complete store configuration: ```bash...(ENGLISH_WORD_REPEAT_RULE)
[duplication] ~259-~259: Possible typo: you repeated a word.
Context: ...t --tests store.fga.yaml### Store Export Export store configuration to file:bash fg...(ENGLISH_WORD_REPEAT_RULE)
README.md (2)
231-231: Clarify and standardize parameter description
The--fileparameter should explicitly reference the store file and uppercase “YAML”. For example:-* `--file`: File containing the store. See [Store File Format](docs/STORE_FILE.md) for detailed documentation. +* `--file`: Path to the store file (YAML). See [Store File Format](docs/STORE_FILE.md) for detailed documentation.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
231-231: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
528-528: Standardize and clarify the--testsparameter
Update to uppercase “YAML” and clarify it refers to a store test file. For example:-* `--tests`: Name of the tests file. Must be in yaml format. See [Store File Format](docs/STORE_FILE.md) for detailed documentation. +* `--tests`: Path to the store test file (YAML). Must be in YAML format. See [Store File Format](docs/STORE_FILE.md) for detailed documentation.🧰 Tools
🪛 LanguageTool
[uncategorized] ~528-~528: Loose punctuation mark.
Context: ...test ###### Parameters *--tests: Name of the tests file. Must be in yaml...(UNLIKELY_OPENING_PUNCTUATION)
🪛 markdownlint-cli2 (0.17.2)
528-528: Unordered list style
Expected: dash; Actual: asterisk(MD004, ul-style)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
README.md(3 hunks)docs/STORE_FILE.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
README.md
231-231: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
528-528: Unordered list style
Expected: dash; Actual: asterisk
(MD004, ul-style)
🪛 LanguageTool
README.md
[uncategorized] ~528-~528: Loose punctuation mark.
Context: ...test ###### Parameters * --tests: Name of the tests file. Must be in yaml...
(UNLIKELY_OPENING_PUNCTUATION)
docs/STORE_FILE.md
[uncategorized] ~155-~155: Possible missing preposition found.
Context: ...ner: false #### List Objects Tests Validate which objects a user can access: ya...
(AI_HYDRA_LEO_MISSING_TO)
[duplication] ~247-~247: Possible typo: you repeated a word.
Context: ...I Commands Using Store Files ### Store Import Import a complete store configuration: ```bash...
(ENGLISH_WORD_REPEAT_RULE)
[duplication] ~259-~259: Possible typo: you repeated a word.
Context: ...t --tests store.fga.yaml ### Store Export Export store configuration to file:bash fg...
(ENGLISH_WORD_REPEAT_RULE)
⏰ Context from checks skipped due to timeout of 90000ms (2)
- GitHub Check: Test Release Process
- GitHub Check: Tests
Description
Adds comprehensive documentation for the OpenFGA store file format (
.fga.yaml) as requested in #490.Documentation Coverage
Verification
The documentation covers all CLI commands that use store files:
fga store import --file store.fga.yamlfga model test --tests store.fga.yamlfga store export(outputs store file format)Next Steps
References
fixes #490
Review Checklist
mainSummary by CodeRabbit