docs: Add store file format documentation (mirrored from CLI repo) #1053
Conversation
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the WalkthroughA new documentation file detailing the Changes
Sequence Diagram(s)No sequence diagram is generated as the changes are documentation-only and do not introduce or modify control flow or feature logic. Assessment against linked issues
Assessment against linked issues: Out-of-scope changesNo out-of-scope changes detected. 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. 🪧 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 (
|
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/content/modeling/store-file-format.mdx (1)
18-20: Clarify mirror-notice scope & sync strategyThe “mirrored from CLI repo” notice is helpful, but it doesn’t specify when the last sync occurred or how updates will be tracked. Readers cannot know whether this copy is already stale.
Consider adding a short line such as:
_Last synced: 2025-07-04 · To propose edits, open PRs against the CLI docs._This keeps the maintenance burden explicit and avoids diverging docs down the line.
docs/content/modeling/testing-models.mdx (1)
22-22: Use a consistent link style for intra-doc referencesElsewhere in the doc set you include the
.mdxextension (e.g.../getting-started/perform-check.mdx). For consistency, either:
- Drop extensions everywhere, or
- Append it here:
-For complete details on the `.fga.yaml` store file format, see [Store File Format](./store-file-format). +For complete details on the `.fga.yaml` store file format, see [Store File Format](./store-file-format.mdx).Keeping a single convention avoids broken links in case of future tooling changes.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs/content/modeling/store-file-format.mdx(1 hunks)docs/content/modeling/testing-models.mdx(1 hunks)docs/sidebars.js(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/content/modeling/testing-models.mdx
[grammar] ~22-~22: Use correct spacing
Context: ...amlstore file format, see [Store File Format](./store-file-format). ## Define the model and tuples .fga.yaml...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
docs/content/modeling/store-file-format.mdx
[grammar] ~12-~12: Use correct spacing
Context: ...uctNameFormat, RelatedSection, } from '@components/Docs'; # Store File Format <DocumentationNotice...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~14-~14: Use correct spacing
Context: ... from '@components/Docs'; # Store File Format :::note This documentation is mirrored ...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~19-~19: Use correct spacing
Context: ... please refer to the CLI documentation. ::: The store file is a YAML configuration ...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~22-~22: Use correct spacing
Context: ... format={ProductNameFormat.ShortForm}/> configurations. ## File Structure The store file uses YAM...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~24-~24: Use correct spacing
Context: ...t.ShortForm}/> configurations. ## File Structure The store file uses YAML syntax and sup...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~26-~26: Use correct spacing
Context: ...ax and supports the following top-level properties: yaml name: "Store Name" # Required: Name of the store model_file: "./model.fga" # Path to authorization model file model: | # OR inline model definition model schema 1.1 type user # ... more model definitions tuple_file: "./tuples.yaml" # Path to tuples file tuples: # OR inline tuples - user: user:anne relation: viewer object: document:1 tests: # Test definitions - name: "test-name" description: "Test description" # Optional tuple_file: "./test-tuples.yaml" # Test-specific tuples file tuples: # OR inline test tuples - user: user:bob relation: editor object: document:2 check: # Authorization checks - user: user:anne object: document:1 context: # Optional context for ABAC timestamp: "2023-05-03T21:25:23+00:00" assertions: viewer: true editor: false list_objects: # List objects tests - user: user:anne type: document context: # Optional context timestamp: "2023-05-03T21:25:23+00:00" assertions: viewer: - document:1 - document:2 list_users: # List users tests - object: document:1 user_filter: - type: user context: # Optional context timestamp: "2023-05-03T21:25:23+00:00" assertions: viewer: users: - user:anne - user:bob ## Core Components ### 1. Store Metadata ...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~81-~81: Use correct spacing
Context: ...e - user:bob ``` ## Core Components ### 1. Store Metadata - name (requir...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~83-~83: There might be a problem here.
Context: ...b ``` ## Core Components ### 1. Store Metadata - name (required): The display name for the store - This n...
(QB_NEW_EN_MERGED_MATCH)
[grammar] ~85-~85: There might be a mistake here.
Context: ...** (required): The display name for the store - This name is used when creating a new store ...
(QB_NEW_EN_OTHER)
[grammar] ~86-~86: There might be a mistake here.
Context: ...e is used when creating a new store via import ### 2. Authorization Model You can specify...
(QB_NEW_EN_OTHER)
[grammar] ~88-~88: Use correct spacing
Context: ... store via import ### 2. Authorization Model You can specify the authorization model...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~90-~90: Use correct spacing
Context: ... specify the authorization model in two ways: #### Option A: External File Reference ```ya...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~92-~92: Use correct spacing
Context: ...two ways: #### Option A: External File Reference yaml model_file: "./path/to/model.fga" #### Option B: Inline Model Definition ```ya...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~97-~97: Use correct spacing
Context: ...l.fga" #### Option B: Inline Model Definitionyaml model: | model schema 1.1 type user type document relations define viewer: [user] define editor: [user] and viewer ``` The model defines the authorization sch...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~111-~111: There might be a problem here.
Context: ...`` The model defines the authorization schema including: - Types (user, document, folder, etc.) - R...
(QB_NEW_EN_MERGED_MATCH)
[grammar] ~112-~112: Use a period to end declarative sentences
Context: ...uding: - Types (user, document, folder, etc.) - Relations (viewer, editor, owner, etc...
(QB_NEW_EN_OTHER_ERROR_IDS_25)
[grammar] ~114-~114: Use correct spacing
Context: ...wner, etc.) - Authorization rules and conditions ### 3. Relationship Tuples Tuples define t...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~116-~116: Use correct spacing
Context: ...les and conditions ### 3. Relationship Tuples Tuples define the actual relationships ...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~118-~118: Use correct spacing
Context: ...nd objects. You can specify them in two ways: #### Option A: External File Reference ```ya...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~120-~120: Use correct spacing
Context: ...two ways: #### Option A: External File Reference yaml tuple_file: "./path/to/tuples.yaml" #### Option B: Inline Tuple Definition ```ya...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~125-~125: Use correct spacing
Context: ....yaml" #### Option B: Inline Tuple Definitionyaml tuples: - user: user:anne relation: viewer object: document:1 - user: user:bob relation: editor object: document:1 condition: # Optional: for conditional relationships name: valid_ip context: ip_address: "192.168.1.100" ``` Supported tuple file formats: - YAML ...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~143-~143: Use correct spacing
Context: ....yaml, .yml) - JSON (.json) - CSV (.csv) ### 4. Tests The tests array contains te...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~145-~145: Use correct spacing
Context: ...- JSON (.json) - CSV (.csv) ### 4. Tests The tests array contains test cases t...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~147-~147: Use correct spacing
Context: ...o validate your authorization model and tuples. #### Test Structure Each test can include: -...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~150-~150:
Context: ...les. #### Test Structure Each test can include: - name (required): Test identifier - description (op...
(QB_NEW_EN_OTHER_ERROR_IDS_)
[grammar] ~151-~151:
Context: ... include: - name (required): Test identifier - description (optional): Human-readable test description - **`tu...
(QB_NEW_EN_OTHER_ERROR_IDS_)
[grammar] ~152-~152:
Context: ...tion** (optional): Human-readable test description - **tuple_file** or **tuples`**: Test-specific relationshi...
(QB_NEW_EN_OTHER_ERROR_IDS_)
[grammar] ~156-~156: Use correct spacing
Context: ...ts - list_users: List users API tests #### Check Tests Validate whether a user has...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~159-~159: Use correct spacing
Context: ...her a user has specific relations to an object: yaml check: - user: user:anne object: document:1 context: # Optional: for ABAC conditions current_time: "2023-05-03T21:25:23+00:00" user_ip: "192.168.0.1" assertions: viewer: true # Expected result editor: false owner: false #### List Objects Tests Validate which objec...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~175-~175: Use correct spacing
Context: ...Tests Validate which objects a user can access: yaml list_objects: - user: user:anne type: document # Object type to query context: # Optional context current_time: "2023-05-03T21:25:23+00:00" assertions: viewer: # Objects user can view - document:1 - document:2 editor: # Objects user can edit - document:1 #### List Users Tests Validate which users h...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~191-~191: There might be a mistake here.
Context: ...dit - document:1 ``` #### List Users Tests Validate which users have access ...
(QB_NEW_EN_OTHER)
[grammar] ~192-~192: Use correct spacing
Context: ... Validate which users have access to an object: yaml list_users: - object: document:1 user_filter: # Filter by user types - type: user - type: team context: # Optional context current_time: "2023-05-03T21:25:23+00:00" assertions: viewer: users: - user:anne - user:bob ## Context Support (ABAC) The store file ...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~209-~209: Use correct spacing
Context: ... - user:bob ``` ## Context Support (ABAC) The store file supports Attribute-Based...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~211-~211: Use correct spacing
Context: ...ccess Control (ABAC) through contextual information: yaml # In tuples - for conditional relationships tuples: - user: user:anne relation: viewer object: document:1 condition: name: non_expired_grant context: grant_timestamp: "2023-05-03T21:25:20+00:00" grant_duration: "10m" # In tests - for contextual evaluations tests: - name: "time-based-access" check: - user: user:anne object: document:1 context: current_timestamp: "2023-05-03T21:25:23+00:00" assertions: viewer: true ## File Composition The store file suppor...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~237-~237: Use correct spacing
Context: ...ns: viewer: true ``` ## File Composition The store file supports flexible compos...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~239-~239: Use correct spacing
Context: ...ition The store file supports flexible composition: ### Global + Test-Specific Data - **Global ...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~244-~244: There might be a mistake here.
Context: ...h tuple_file and tuples can be used together ### Mixed Inline and File References ```yam...
(QB_NEW_EN_OTHER)
[grammar] ~246-~246: Use correct spacing
Context: ...sed together ### Mixed Inline and File References yaml name: "Mixed Example" model_file: "./model.fga" # Model from file tuples: # Inline global tuples - user: user:admin relation: owner object: system:main tests: - name: "test-1" tuple_file: "./test1-tuples.yaml" # Additional tuples from file check: - user: user:admin object: system:main assertions: owner: true ## CLI Commands Using Store Files ### Sto...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~264-~264: Use correct spacing
Context: ...: true ``` ## CLI Commands Using Store Files ### Store Import Import a complete store co...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~267-~267: Use correct spacing
Context: ...## Store Import Import a complete store configuration: bash fga store import --file store.fga.yaml ### Model Testing Run tests against an au...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~273-~273: Use correct spacing
Context: ...ng Run tests against an authorization model: bash fga model test --tests store.fga.yaml ### Store Export Export store configuration...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~279-~279: There might be a problem here.
Context: ...re Export Export store configuration to file: bash fga store export --store-id 01H0H015178Y2V4CX10C2KGHF4 > exported-store.fga.yaml ## Examples ### Basic Store File ```yaml name: "Documen...
(QB_NEW_EN_MERGED_MATCH)
[grammar] ~286-~286: Use correct spacing
Context: ....yaml ## Examples ### Basic Store Fileyaml name: "Document Management" model_file: "./authorization-model.fga" tuple_file: "./relationships.yaml" tests: - name: "basic-permissions" check: - user: user:alice object: document:readme assertions: viewer: true editor: false ### Advanced Store with ABACyaml name: ...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~301-~301: Use correct spacing
Context: ...tor: false ### Advanced Store with ABACyaml name: "Time-Based Access" model: | model schema 1.1 type user type document relations define viewer: [user with non_expired_grant] condition non_expired_grant(current_time: timestamp, grant_time: timestamp, duration: duration) { current_time < grant_time + duration } tuples: - user: user:bob relation: viewer object: document:secret condition: name: non_expired_grant context: grant_time: "2023-05-03T21:25:20+00:00" duration: "1h" tests: - name: "time-expiry-test" check: - user: user:bob object: document:secret context: current_time: "2023-05-03T21:30:00+00:00" # Within 1 hour assertions: viewer: true - user: user:bob object: document:secret context: current_time: "2023-05-03T22:30:00+00:00" # After 1 hour assertions: viewer: false ### Multi-Test Store Fileyaml name: "Co...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~344-~344: Use correct spacing
Context: ...viewer: false ### Multi-Test Store Fileyaml name: "Comprehensive Testing" model_file: "./model.fga" tuple_file: "./base-tuples.yaml" tests: - name: "admin-permissions" tuples: - user: user:admin relation: owner object: system:config check: - user: user:admin object: system:config assertions: owner: true viewer: true list_objects: - user: user:admin type: system assertions: owner: - system:config - name: "user-permissions" tuple_file: "./user-test-tuples.yaml" check: - user: user:john object: document:public assertions: viewer: true editor: false list_users: - object: document:public user_filter: - type: user assertions: viewer: users: - user:john - user:jane ``` ## Best Practices 1. **Use descriptive na...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~388-~388: Use correct spacing
Context: ... - user:jane ``` ## Best Practices 1. Use descriptive names: Make store and...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~390-~390: There might be a mistake here.
Context: ...**: Make store and test names clear and meaningful 2. Organize with external files: Fo...
(QB_NEW_EN_OTHER)
[grammar] ~391-~391: There might be a mistake here.
Context: ... files for models and .yaml files for tuples 3. Comprehensive testing: Include c...
(QB_NEW_EN_OTHER)
[grammar] ~392-~392: There might be a mistake here.
Context: ...nd list_users tests to validate all API behaviors 4. Context testing: When using ABAC...
(QB_NEW_EN_OTHER)
[grammar] ~393-~393: There might be a mistake here.
Context: ...d negative cases with different context values 5. Modular tuples: Use both global ...
(QB_NEW_EN_OTHER)
[grammar] ~394-~394: There might be a mistake here.
Context: ...lobal and test-specific tuples to avoid repetition 6. Version control: Store files wor...
(QB_NEW_EN_OTHER)
[grammar] ~395-~395: There might be a mistake here.
Context: ...for tracking authorization changes over time ## File Extensions - Store files: `.f...
(QB_NEW_EN_OTHER)
[grammar] ~397-~397: Use correct spacing
Context: ...uthorization changes over time ## File Extensions - Store files: .fga.yaml (recommended...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~401-~401: Use correct spacing
Context: ...d- **Tuple files**:.yaml, .json, or .csv The.fga.yaml` extension is the conve...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~403-~403: Use correct spacing
Context: ...ily identifiable and helps with tooling integration. <RelatedSection description="Learn mo...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: Run Checks
- GitHub Check: markdown-link-check-md
- GitHub Check: deploy-preview
- GitHub Check: Test deployment
🔇 Additional comments (1)
docs/sidebars.js (1)
228-232: Sidebar entry looks goodThe new “Store File Format” doc is correctly positioned after “Testing Models” and the
idmatches the MDX path. No issues spotted.
There was a problem hiding this comment.
Thanks @Siddhant-K-code! Just a tiny comment to fix linking and build
Co-authored-by: Raghd Hamzeh <raghd@rhamzeh.com>
Description
Adds store file format documentation to the modeling section as a mirror of the primary documentation in the CLI repository, as requested in openfga/cli#490
Documentation Structure
/docs/modeling/store-file-formatMirror Notice
The documentation includes a clear notice that it's mirrored from the CLI repository and directs users to the CLI docs for the most up-to-date version.
Integration
References
fixes openfga/cli#490
Review Checklist
mainSummary by CodeRabbit
.fga.yaml), including structure, usage, examples, CLI integration, and best practices.