chore(docs): clarify Check API behavior for undefined relations

[maxloge]

Description

The "Getting Started" use inconsistent relationship names between the Update Relationship Tuples and Perform a Check sections:

Step	Page	Relation
1. Create tuple	update-tuples.mdx	reader
2. Check tuple	perform-check.mdx	can_view

Someone who follows the instructions in order will receive a 400 Bad Request / ValidationException when calling the Check API, even though the example in the doc claims that the result is allowed: true.

A user following the example in Python with

    body = ClientCheckRequest(
        user="user:anne",
        relation="can_view",
        object="document:Z",
    )

would get the following Traceback:

Traceback (most recent call last):
  File "<string>", line 6, in <module>
  File "<string>", line 2, in <module>
  File "/home/vscode/.local/lib/python3.10/site-packages/openfga_sdk/sync/client/client.py", line 650, in check
    api_response = self._api.check(body=req_body, **kwargs)
  File "/home/vscode/.local/lib/python3.10/site-packages/openfga_sdk/sync/open_fga_api.py", line 255, in check
    return self.check_with_http_info(body, **kwargs)
  File "/home/vscode/.local/lib/python3.10/site-packages/openfga_sdk/sync/open_fga_api.py", line 388, in check_with_http_info
    return self.api_client.call_api(
  File "/home/vscode/.local/lib/python3.10/site-packages/openfga_sdk/sync/api_client.py", line 565, in call_api
    return self.__call_api(
  File "/home/vscode/.local/lib/python3.10/site-packages/openfga_sdk/sync/api_client.py", line 344, in __call_api
    raise e
  File "/home/vscode/.local/lib/python3.10/site-packages/openfga_sdk/sync/api_client.py", line 278, in __call_api
    response_data = self.request(
  File "/home/vscode/.local/lib/python3.10/site-packages/openfga_sdk/sync/api_client.py", line 641, in request
    return self.rest_client.request(
  File "/home/vscode/.local/lib/python3.10/site-packages/openfga_sdk/sync/rest.py", line 507, in request
    self.handle_response_exception(raw_response)
  File "/home/vscode/.local/lib/python3.10/site-packages/openfga_sdk/sync/rest.py", line 333, in handle_response_exception
    raise ValidationException(http_resp=response)
openfga_sdk.exceptions.ValidationException: (400)
Reason: Bad Request

I've also updated the explanation regarding the result since:

export FGA_API_URL=http://openfga:8080 && \
export FGA_STORE_ID=01JSWBHVGB4VSPPNCCV8R4SBSW && \
export FGA_MODEL_ID=01JSWQNDX7MPVM29P39ACTH9EN

$ curl -i -s -X POST \
  "${FGA_API_URL}/stores/${FGA_STORE_ID}/check" \
  -H "Content-Type: application/json" \
  -d '{
    "authorization_model_id": "'"${FGA_MODEL_ID}"'",
    "tuple_key": {
      "user": "user:anne",
      "relation": "reader",
      "object": "document:Z"
    }
  }' && printf "\n"

returns

HTTP/1.1 200 OK
Content-Type: application/json
Openfga-Authorization-Model-Id: 01JSWQNDX7MPVM29P39ACTH9EN
Openfga-Store-Id: 01JSWBHVGB4VSPPNCCV8R4SBSW
Vary: Origin
X-Request-Id: 50d7c9e8-2400-4e48-bdea-3c42a07f9183
Date: Tue, 29 Apr 2025 02:15:53 GMT
Content-Length: 32

{"allowed":true,"resolution":""}

$ curl -i -s -X POST \
  "${FGA_API_URL}/stores/${FGA_STORE_ID}/check" \
  -H "Content-Type: application/json" \
  -d '{
    "authorization_model_id": "'"${FGA_MODEL_ID}"'",
    "tuple_key": {
      "user": "user:anne",
      "relation": "writer",
      "object": "document:Z"
    }
  }' && printf "\n"

returns

HTTP/1.1 200 OK
Content-Type: application/json
Openfga-Authorization-Model-Id: 01JSWQNDX7MPVM29P39ACTH9EN
Openfga-Store-Id: 01JSWBHVGB4VSPPNCCV8R4SBSW
Vary: Origin
X-Request-Id: c06bbc2d-d326-4422-8e59-16e92edee840
Date: Tue, 29 Apr 2025 02:16:16 GMT
Content-Length: 33

{"allowed":false,"resolution":""}

and

$ curl -i -s -X POST \
  "${FGA_API_URL}/stores/${FGA_STORE_ID}/check" \
  -H "Content-Type: application/json" \
  -d '{
    "authorization_model_id": "'"${FGA_MODEL_ID}"'",
    "tuple_key": {
      "user": "user:anne",
      "relation": "can_view",
      "object": "document:Z"
    }
  }' && printf "\n"

returns

HTTP/1.1 400 Bad Request
Content-Type: application/json
Openfga-Authorization-Model-Id: 01JSWQNDX7MPVM29P39ACTH9EN
Openfga-Store-Id: 01JSWBHVGB4VSPPNCCV8R4SBSW
Vary: Origin
X-Request-Id: afff79c3-cf8b-4d9d-a7fa-c9bd189786f9
Date: Tue, 29 Apr 2025 02:16:40 GMT
Content-Length: 79

{"code":"validation_error","message":"relation 'document#can_view' not found"}

Fix

In perform-check.mdx, change the example relation from can_view to reader so it matches the tuple created in the previous page and the relation that is used in the other pages of the Getting Started section of the documentation.

After the fix, the end-to-end example executed by a user reading the documentation linearly using the instructions of the precedent page will works as expected.

The explanation below the example regarding the expected result has also been updated to be more specific.

References

The mismatch is visible on these pages:

• Tuple write example (uses reader): https://openfga.dev/docs/getting-started/update-tuples#02-calling-write-api-to-add-new-relationship-tuples
• Check example (uses can_view): https://openfga.dev/docs/getting-started/perform-check#02-calling-check-api

Review Checklist

• I have clicked on "allow edits by maintainers".
• I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
• The correct base branch is being used, if not main
• I have added tests to validate that the change in functionality is working as expected

Summary by CodeRabbit

• Documentation
  • Clarified Check API response documentation to specify distinct outcomes: allowed: true for existing relationships, allowed: false for defined but missing relationships, and 400 Bad Request for undefined relations.

[rhamzeh]

Thanks @maxloge - will take a look at this soon!

[coderabbitai]

Walkthrough

Documentation update to the Check API response specification clarifying the allowed field behavior across three scenarios: returns true when a relationship exists, false when the relation is defined but no matching tuple exists, and 400 Bad Request when the relation is not defined in the model.

Changes

Cohort / File(s)	Summary
Documentation Updates docs/content/getting-started/perform-check.mdx	Clarified Check API response semantics for the allowed field, specifying distinct behaviors for existing relationships, defined-but-unmatched relations, and undefined relations.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title 'docs: clarify Check API behavior for undefined relations' accurately reflects the main change: updating documentation to clarify the Check API's response semantics for undefined relations.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[Copilot]

Pull request overview

This PR updates the “Getting Started” Check API documentation to better explain how to interpret the allowed field in Check responses and what happens when a relation is not present in the authorization model.

Changes:

• Clarifies when allowed is true vs false in the Check API response.
• Adds a note that an undefined relation in the model results in a 400 Bad Request rather than allowed: false.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/content/getting-started/perform-check.mdx (1)

214-214: ⚠️ Potential issue | 🟡 Minor

Update BatchCheck documentation to match the three-case semantics.

Line 214 still describes only the two-case behavior (true/false) without mentioning that undefined relations will cause a 400 Bad Request error, just like the single Check API. This is inconsistent with the updated documentation on lines 166-170.

📝 Proposed update for consistency

-The result will include an `allowed` field for each authorization check that will return `true` if the relationship exists and `false` if the relationship does not exist.
+The result will include an `allowed` field for each authorization check that will return `true` if the relationship exists and `false` if the relation is defined in your model but no matching tuple exists. If any relation is not defined in your model, the API will return a `400 Bad Request` error for the entire batch.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/content/getting-started/perform-check.mdx` at line 214, Update the
BatchCheck docs to describe the three-case semantics: instead of saying each
authorization check returns only true/false, state that BatchCheck results can
be allowed (true), denied (false), or trigger a 400 Bad Request when an
undefined relation is referenced (same behavior as the single Check API); edit
the sentence referencing "allowed" to include these three outcomes and mention
BatchCheck and the single Check API to keep the documentation consistent.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@docs/content/getting-started/perform-check.mdx`:
- Line 214: Update the BatchCheck docs to describe the three-case semantics:
instead of saying each authorization check returns only true/false, state that
BatchCheck results can be allowed (true), denied (false), or trigger a 400 Bad
Request when an undefined relation is referenced (same behavior as the single
Check API); edit the sentence referencing "allowed" to include these three
outcomes and mention BatchCheck and the single Check API to keep the
documentation consistent.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2fc69378-fd57-49d2-b683-56cd9c8a9055

📥 Commits

Reviewing files that changed from the base of the PR and between 835194a and 95ab428.

📒 Files selected for processing (1)

• docs/content/getting-started/perform-check.mdx

[rhamzeh]

Thanks @maxloge - sorry this feel by the way side (for a whole year 🙈 ).

I took the liberty to update the title of your PR as the actual changes don't match the current title or description - if that is not what you intended, please let us know!