Open
Conversation
Contributor
📝 WalkthroughWalkthroughAdds SCIM 2.0 Schema API documentation across Asgardeo and Identity Server docs: OpenAPI/Swagger specs declaring Changes
Suggested labels
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds SCIM 2.0 Schemas API documentation pages (Redoc) and corresponding API definition files, and wires them into the MkDocs navigation for both Asgardeo and WSO2 Identity Server docs.
Changes:
- Added new Redoc pages for the SCIM 2.0 Schemas API in Asgardeo, Identity Server
next, and Identity Server7.2.0. - Added new API definition YAML files for the Schemas endpoints under each product/version.
- Updated MkDocs navigation to expose the new Schemas API pages under SCIM 2.0.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 16 comments.
Show a summary per file
| File | Description |
|---|---|
| en/identity-server/next/mkdocs.yml | Adds the SCIM 2.0 Schemas API page to the SCIM navigation. |
| en/identity-server/next/docs/apis/scim2/scim2-schema-rest-api.md | New Redoc page rendering the Schemas API spec. |
| en/identity-server/next/docs/apis/restapis/scim2-schemas.yaml | New Schemas API definition (currently Swagger 2.0). |
| en/identity-server/7.2.0/mkdocs.yml | Adds the SCIM 2.0 Schemas API page to the SCIM navigation. |
| en/identity-server/7.2.0/docs/apis/scim2/scim2-schema-rest-api.md | New Redoc page rendering the Schemas API spec. |
| en/identity-server/7.2.0/docs/apis/restapis/scim2-schemas.yaml | New Schemas API definition (currently Swagger 2.0). |
| en/asgardeo/mkdocs.yml | Adds the SCIM 2.0 Schemas API page to the SCIM navigation. |
| en/asgardeo/docs/apis/scim2/scim2-schema-rest-api.md | New Redoc page rendering the Schemas API spec. |
| en/asgardeo/docs/apis/restapis/scim2-schemas.yaml | New OpenAPI 3.0 spec for Schemas API (success responses currently documented as application/json). |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@en/asgardeo/docs/apis/scim2/scim2-schema-rest-api.md`:
- Line 5: The file ends without a trailing newline causing MD047; add a single
newline character at the end of the file so the final line containing the <redoc
spec-url="{{base_path}}/apis/restapis/scim2-schemas.yaml"
theme='{{redoc_theme}}'></redoc> tag is terminated by one newline (ensure only
one final newline and no extra blank lines).
In `@en/identity-server/7.2.0/docs/apis/restapis/scim2-schemas.yaml`:
- Around line 363-366: The OpenAPI schemas ErrorUnauthorized and
ErrorSchemaNotFound declare a required field named "schema" which does not exist
under properties (the actual property is "schemas"); update the required arrays
in the ErrorUnauthorized and ErrorSchemaNotFound schema definitions to replace
"schema" with "schemas" so the required list matches the defined property name.
- Around line 28-30: The OpenAPI file declares global security schemes (OAuth2
and BasicAuth) but the operations labeled "No permissions required" are
ambiguous about whether authentication is required; to fix, either add
operation-level security: [] to each relevant operation (the SCIM endpoints
around the "No permissions required" descriptions) to explicitly opt-out of
global authentication, or update the endpoint descriptions to explicitly state
"authentication required, but no special scopes/permissions required" so callers
know 401 responses refer to missing credentials rather than missing scopes;
locate and change the operation entries that currently include the "No
permissions required" text to apply one of these two fixes.
- Around line 24-25: The SCIM response media type is being overridden locally
with "application/json", causing non-compliance; locate the local "produces"
entries that list "application/json" (the ones overriding the global produces)
and either remove those local "produces" keys so the document inherits the
global produces "application/scim+json", or change their values from
"application/json" to "application/scim+json" so all responses use the
SCIM-mandated media type.
In `@en/identity-server/next/docs/apis/restapis/scim2-schemas.yaml`:
- Around line 363-366: The SCIM schema models ErrorUnauthorized and
ErrorSchemaNotFound have an incorrect required field name ("schema") that should
be "schemas"; update the required arrays for ErrorUnauthorized,
ErrorSchemaNotFound (and the other repeated occurrences noted) to use "schemas"
so they match the defined property name "schemas" in the YAML models, ensuring
schema validation passes.
- Around line 28-30: The global security block declares OAuth2/BasicAuth but two
operations are documented as "No permissions required", creating a
contradiction; fix by either adding an explicit operation-level override
security: [] to those specific operations to make them publicly accessible, or
update their operation descriptions to explicitly state that authentication is
required but no additional roles/scopes are needed (e.g., "Authentication
required; no extra roles/scopes required")—locate the operations that contain
the "No permissions required" text and apply one of these two changes
accordingly.
- Around line 24-25: The GET operations for the /Schemas and /Schemas/{id} paths
currently override the global produces with application/json; update those
operation-level media types to application/scim+json so they match the global
declaration and RFC 7644: locate the GET entries under the /Schemas and
/Schemas/{id} path items and replace any occurrence of application/json in their
produces/response content with application/scim+json (ensuring the response
schema remains the same).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: c091dc2f-dd55-486b-8fb5-759d3c3302f0
📒 Files selected for processing (9)
en/asgardeo/docs/apis/restapis/scim2-schemas.yamlen/asgardeo/docs/apis/scim2/scim2-schema-rest-api.mden/asgardeo/mkdocs.ymlen/identity-server/7.2.0/docs/apis/restapis/scim2-schemas.yamlen/identity-server/7.2.0/docs/apis/scim2/scim2-schema-rest-api.mden/identity-server/7.2.0/mkdocs.ymlen/identity-server/next/docs/apis/restapis/scim2-schemas.yamlen/identity-server/next/docs/apis/scim2/scim2-schema-rest-api.mden/identity-server/next/mkdocs.yml
Contributor
There was a problem hiding this comment.
Actionable comments posted: 7
♻️ Duplicate comments (1)
en/identity-server/7.2.0/docs/apis/restapis/scim2-schemas.yaml (1)
72-74:⚠️ Potential issue | 🟡 MinorAlign auth wording for
/Schemas/{id}with global security requirements.Line 74 says “No permissions required”, which is still ambiguous against global auth and inconsistent with Line 43 wording used in
/Schemas. Use the same explicit phrasing (“no additional roles/scopes; authentication required”) here too.Suggested wording update
- * No permissions required + * No additional roles or scopes required. Authentication is required.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/identity-server/7.2.0/docs/apis/restapis/scim2-schemas.yaml` around lines 72 - 74, Update the wording under the /Schemas/{id} endpoint so it matches the global security phrasing used for /Schemas: replace the ambiguous "No permissions required" text with the explicit phrase "No additional roles/scopes; authentication required" (locate the block associated with the /Schemas/{id} path and its Permission required section to make the change).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@en/asgardeo/docs/apis/restapis/scim2-schemas.yaml`:
- Line 47: Update the cURL examples that set the Accept header string "-H
'accept: application/json' \" to use the SCIM media type "-H 'accept:
application/scim+json' \" so the request Accept header matches the documented
response media type; apply the same replacement to all instances (e.g., the
occurrences shown in the examples).
- Around line 12-21: The OpenAPI spec currently only notes authentication in the
description for the operationId getSchemas (paths /Schemas) and similar for GET
/Schemas/{id}; add a proper OpenAPI security definition by adding a
components.securitySchemes entry (e.g., OAuth2, bearerAuth, or the
organization’s chosen scheme) and then reference it via a security
requirement—either globally under top-level security or per-operation under
paths./Schemas.get.security and paths./Schemas/{id}.get.security—so tools and
generators enforce authentication instead of relying on prose.
- Around line 331-333: The OpenAPI SCIM error schemas define the "schemas"
property as a string but RFC 7644 requires it to be an array of unique string
URIs; update the ErrorUnauthorized and ErrorSchemaNotFound schema definitions to
change the "schemas" field from type: string to type: array with items: { type:
string } (and keep the example as an array like
["urn:ietf:params:scim:api:messages:2.0:Error"]) so both schemas comply with
SCIM 2.0 and downstream validation/generation; locate the "ErrorUnauthorized"
and "ErrorSchemaNotFound" schema objects and modify their "schemas" property
accordingly.
In `@en/identity-server/7.2.0/docs/apis/restapis/scim2-schemas.yaml`:
- Around line 370-372: The OpenAPI definition models the SCIM error object's
"schemas" property as a string; change the property type to an array of strings
and update the example to an array of URNs so it matches SCIM (e.g., type:
array, items: { type: string, format: uri? }, example:
["urn:ietf:params:scim:api:messages:2.0:Error"]). Update both occurrences
referenced (the block around the current schemas example and the similar block
at the later occurrence) and ensure any validations or descriptions for
"schemas" reflect that it is an array of schema URNs.
In `@en/identity-server/next/docs/apis/restapis/scim2-schemas.yaml`:
- Around line 38-44: Update the description for the /Schemas/{id} endpoint to
match the /Schemas listing: change the phrase "No permissions required" to "No
additional roles or scopes required. Authentication is required." so the
operation (e.g., operationId getSchemaById or the /Schemas/{id} path)
consistently clarifies that authentication is required even though no extra
roles/scopes are needed; ensure the text formatting and surrounding
markdown/HTML match the existing /Schemas description (operationId getSchemas)
for consistency.
- Around line 155-205: Update the SCIM schema enums to RFC 7643-compliant casing
and values: change the values in the "type" enum (used in the attribute
definition) from uppercase (e.g., STRING, COMPLEX, BOOLEAN, DECIMAL, INTEGER,
DATE_TIME, DATE, BINARY, REFERENCE) to RFC forms (e.g., "string", "complex",
"boolean", "decimal", "integer", "dateTime", "binary", "reference") and verify
whether "DATE" is a vendor extension (remove it if not allowed); change
"mutability" enum values in the mutability property from
READ_ONLY/READ_WRITE/IMMUTABLE/WRITE_ONLY to
"readOnly"/"readWrite"/"immutable"/"writeOnly"; change "returned" enum values
from ALWAYS/NEVER/DEFAULT/REQUEST to "always"/"never"/"default"/"request"; and
expand the "uniqueness" enum to include "none", "server", and "global" (not just
NONE), ensuring examples match the new values (e.g., "string", "readWrite",
"default", "none").
- Around line 370-372: The schemas property for the SCIM error schemas
(ErrorUnauthorized and ErrorSchemaNotFound) is incorrectly declared as a string;
change each schemas property to be an array of strings per RFC 7644 Section 3.12
(i.e., type: array with items: type: string) and update the example to be an
array containing the URI (e.g., ["urn:ietf:params:scim:api:messages:2.0:Error"])
so both ErrorUnauthorized and ErrorSchemaNotFound conform to the SCIM 2.0 spec.
---
Duplicate comments:
In `@en/identity-server/7.2.0/docs/apis/restapis/scim2-schemas.yaml`:
- Around line 72-74: Update the wording under the /Schemas/{id} endpoint so it
matches the global security phrasing used for /Schemas: replace the ambiguous
"No permissions required" text with the explicit phrase "No additional
roles/scopes; authentication required" (locate the block associated with the
/Schemas/{id} path and its Permission required section to make the change).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 1ef77d5d-ac91-4139-84e4-7ec51e334893
📒 Files selected for processing (3)
en/asgardeo/docs/apis/restapis/scim2-schemas.yamlen/identity-server/7.2.0/docs/apis/restapis/scim2-schemas.yamlen/identity-server/next/docs/apis/restapis/scim2-schemas.yaml
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Purpose
This pull request adds documentation and OpenAPI/Swagger definitions for the SCIM 2.0 Schema API to both the Asgardeo and Identity Server documentation. It introduces new YAML files describing the API endpoints and integrates them into the documentation navigation and Redoc rendering system, making it easier for users to explore and understand the SCIM 2.0 Schema API.
SCIM 2.0 Schema API Documentation Integration
Asgardeo Documentation:
en/asgardeo/docs/apis/restapis/scim2-schemas.yaml, including endpoints to retrieve all schemas and a schema by ID, with detailed schema object definitions and error responses.en/asgardeo/docs/apis/scim2/scim2-schema-rest-api.md.en/asgardeo/mkdocs.ymlto include the new SCIM 2.0 Schema API documentation page.Identity Server Documentation:
en/identity-server/7.2.0/docs/apis/restapis/scim2-schemas.yaml, detailing endpoints, schema objects, security, and error responses.en/identity-server/7.2.0/docs/apis/scim2/scim2-schema-rest-api.md.en/identity-server/7.2.0/mkdocs.ymlto include the new SCIM 2.0 Schema API documentation page.Related Issues