LCORE-973: updated OpenAPI schema #857
Conversation
WalkthroughThis PR enriches OpenAPI schema metadata and documentation by adding descriptive field titles and expanded descriptions to configuration components across three documentation files without altering underlying data structures, required fields, or functional code. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes These changes follow a consistent, repetitive pattern of documentation enrichment (title/description additions across multiple schemas and files). Verify that descriptions are accurate, consistent across all three documentation files, and align with the actual configuration behavior without introducing inadvertent misstatements about functionality or usage constraints. Possibly related PRs
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ 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 |
![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
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
docs/openapi.json (3)
4673-4712: Prevent invalid CORS combo: '*' with credentialsBrowsers reject Access-Control-Allow-Origin="" when credentials are enabled. Add a schema guard so configs with allow_credentials=true cannot include "" in allow_origins.
Apply this diff inside CORSConfiguration (after description):
"title": "CORSConfiguration", - "description": "CORS configuration.\n\nCORS or 'Cross-Origin Resource Sharing' refers to the situations when a\n+ "description": "CORS configuration.\n\nCORS or 'Cross-Origin Resource Sharing' refers to the situations when a frontend running in a browser has JavaScript code that communicates with a backend, and the backend is in a different 'origin' than the frontend. @@ - - [What is CORS?](https://dev.to/akshay_chauhan/what-is-cors-explained-8f1)" + - [What is CORS?](https://dev.to/akshay_chauhan/what-is-cors-explained-8f1)", + "allOf": [ + { + "if": { + "properties": { "allow_credentials": { "const": true } }, + "required": ["allow_credentials"] + }, + "then": { + "properties": { + "allow_origins": { + "not": { "contains": { "const": "*" } } + } + } + } + } + ]
7652-7655: Fix typo: “attatchment” → “attachment” in example messagesMultiple examples contain the misspelling; update for polish and searchability.
- "cause": "Invalid attatchment type: must be one of ['text/plain', 'application/json', 'application/yaml', 'application/xml']", + "cause": "Invalid attachment type: must be one of ['text/plain', 'application/json', 'application/yaml', 'application/xml']",Also applies to: 1376-1379, 1657-1660, 3596-3599, 3879-3881
2610-2612: Grammar nit in examples: “can not” → “cannot”Minor copy fix in deletion responses.
- "response": "Conversation can not be deleted", + "response": "Conversation cannot be deleted",Also applies to: 4976-4978
🧹 Nitpick comments (9)
docs/openapi.json (3)
6185-6250: PostgreSQL: tighten semantics and fix titles (namespace, gssencmode, ssl_mode enums)
- Title tweaks: “Namespace” (not “Name space”); “GSS encryption mode”.
- Constrain ssl_mode/gss_encmode to valid values to prevent misconfig.
- "title": "Name space", + "title": "Namespace", @@ - "title": "SSL mode", - "description": "SSL mode", + "title": "SSL mode", + "description": "SSL mode", + "enum": ["disable","allow","prefer","require","verify-ca","verify-full"], "default": "prefer" @@ - "title": "GSS encmode", - "description": "This option determines whether or with what priority a secure GSS TCP/IP connection will be negotiated with the server.", + "title": "GSS encryption mode", + "description": "Controls negotiation priority for secure GSS TCP/IP connections (libpq gssencmode).", + "enum": ["disable","prefer","require"], "default": "prefer"
6016-6026: Mark URLs with format: uriHelps editors/linters validate config.
- { "type": "string" }, + { "type": "string", "format": "uri" }, { "type": "null" }- "title": "MCP server URL", - "description": "URL of the MCP server" + "title": "MCP server URL", + "description": "URL of the MCP server", + "format": "uri"Also applies to: 6085-6088
4717-4799: Good metadata expansion; consider naming consistencyTitles/descriptions read well. Consider unifying product naming (“Lightspeed Core Stack” vs “Lightspeed Stack”) across the spec to avoid ambiguity.
docs/openapi.md (5)
4029-4029: Optional language style improvement: consider "inaccessible" instead of "not accessible".Lines 4029 and 4527 use the phrase "not accessible to lightspeed-core agents." The term "inaccessible" would be more concise while conveying the same meaning.
Also applies to: 4527-4527
4587-4587: Optional language style improvement: "user name" → "username".Line 4587 refers to "Database user name used to authenticate." Modern convention treats this as one word: "username."
4757-4757: Optional language style improvement: "on a daily basis" is wordy.Line 4757 uses "on a daily basis," which could be shortened to "daily" for conciseness: "for example, daily, set
quota_increase."
4763-4763: Optional markdown/grammar style improvement: "human readable" should be "human-readable".Lines 4763 and 4766 use "human readable" as a descriptor. Modern English convention hyphenates compound adjectives: "human-readable quota limiter name" and "Period specified in human-readable form."
Also applies to: 4766-4766
4003-4005: Minor markdown formatting: unordered list indentation in resource links.Static analysis flags unordered list indentation inconsistencies (lines 4003–4005, 4505–4507, 4953–4955). The resource bullet points use 2-space indentation rather than the expected 0. This is cosmetic and does not affect rendering or functionality, but could be standardized for consistency if desired.
Also applies to: 4505-4507, 4953-4955
docs/output.md (1)
4029-4029: Same optional language and formatting improvements apply to docs/output.md.The same static analysis suggestions noted for docs/openapi.md (lines 4029, 4527 for "inaccessible"; line 4587 for "username"; line 4757 for "daily"; lines 4763, 4766 for "human-readable") apply consistently to this file and may be addressed uniformly across both documentation sources if desired.
Also applies to: 4527-4527, 4587-4587, 4757-4757, 4763-4763, 4766-4766
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
docs/convesation_history.svgis excluded by!**/*.svg
📒 Files selected for processing (3)
docs/openapi.json(25 hunks)docs/openapi.md(12 hunks)docs/output.md(12 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/openapi.md
[style] ~4029-~4029: Consider using “inaccessible” to avoid wordiness.
Context: ...figured in the llama-stack run.yaml are not accessible to lightspeed-core agents. | | authenti...
(NOT_ABLE_PREMIUM)
[style] ~4527-~4527: Consider using “inaccessible” to avoid wordiness.
Context: ...figured in the llama-stack run.yaml are not accessible to lightspeed-core agents. Useful reso...
(NOT_ABLE_PREMIUM)
[style] ~4587-~4587: It’s more common nowadays to write this noun as one word.
Context: ...connect to | | user | string | Database user name used to authenticate | | password | str...
(RECOMMENDED_COMPOUNDS)
[style] ~4757-~4757: ‘on a daily basis’ might be wordy. Consider a shorter alternative.
Context: ...ific value periodically (for example on a daily basis), set quota_increase. | Field | T...
(EN_WORDINESS_PREMIUM_ON_A_DAILY_BASIS)
[grammar] ~4763-~4763: Use a hyphen to join words.
Context: ...luster_limiter | | name | string | Human readable quota limiter name | | initial_...
(QB_NEW_EN_HYPHEN)
[grammar] ~4766-~4766: Use a hyphen to join words.
Context: ...iod | string | Period specified in human readable form | ## QuotaSchedulerConfi...
(QB_NEW_EN_HYPHEN)
docs/output.md
[style] ~4029-~4029: Consider using “inaccessible” to avoid wordiness.
Context: ...figured in the llama-stack run.yaml are not accessible to lightspeed-core agents. | | authenti...
(NOT_ABLE_PREMIUM)
[style] ~4527-~4527: Consider using “inaccessible” to avoid wordiness.
Context: ...figured in the llama-stack run.yaml are not accessible to lightspeed-core agents. Useful reso...
(NOT_ABLE_PREMIUM)
[style] ~4587-~4587: It’s more common nowadays to write this noun as one word.
Context: ...connect to | | user | string | Database user name used to authenticate | | password | str...
(RECOMMENDED_COMPOUNDS)
[style] ~4757-~4757: ‘on a daily basis’ might be wordy. Consider a shorter alternative.
Context: ...ific value periodically (for example on a daily basis), set quota_increase. | Field | T...
(EN_WORDINESS_PREMIUM_ON_A_DAILY_BASIS)
[grammar] ~4763-~4763: Use a hyphen to join words.
Context: ...luster_limiter | | name | string | Human readable quota limiter name | | initial_...
(QB_NEW_EN_HYPHEN)
[grammar] ~4766-~4766: Use a hyphen to join words.
Context: ...iod | string | Period specified in human readable form | ## QuotaSchedulerConfi...
(QB_NEW_EN_HYPHEN)
🪛 markdownlint-cli2 (0.18.1)
docs/output.md
4003-4003: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
4004-4004: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
4005-4005: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
4505-4505: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
4506-4506: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
4507-4507: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
4744-4744: Bare URL used
(MD034, no-bare-urls)
4953-4953: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
4954-4954: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
4955-4955: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
⏰ 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: build-pr
- GitHub Check: Konflux kflux-prd-rh02 / lightspeed-stack-on-pull-request
- GitHub Check: e2e_tests (azure)
- GitHub Check: e2e_tests (ci)
🔇 Additional comments (14)
docs/openapi.json (6)
5145-5146: LGTM: concise, accurate descriptionClearer “Conversation history configuration.” text improves readability.
5738-5740: LGTM: cache config descriptionThe added description clarifies max_entries semantics.
7272-7316: ServiceConfiguration wording improvements look goodHelpful operational guidance (workers, TLS, CORS). No blocking issues.
Also applies to: 7321-7322
7465-7466: TLS docs addition is usefulLinks and context are helpful for operators. No changes requested.
6870-6909: Quota handlers section reads clearlyNice structure (DB choices, limiters, scheduler, token history). No blocking issues.
2-17: Run OpenAPI linters after edits (3.1 dialect)Recommend validating the updated spec to catch any hidden issues (e.g., untyped fields, invalid enums). Consider using Redocly or Spectral with OWASP ruleset to validate against the OpenAPI 3.1 specification.
docs/openapi.md (7)
3997-4006: Strong documentation enhancement for CORS section with practical context and references.The addition of explanatory paragraphs (lines 3997–4006) clearly contextualizes CORS and provides useful external resources. This significantly improves usability for developers unfamiliar with the concept.
4024-4036: Excellent field-level documentation additions to Configuration section.Lines 4024–4036 substantially improve clarity by describing each configuration field's purpose, scope, and relationship to other components. Descriptions of
llama_stack,mcp_servers,authentication,authorization, andquota_handlersare particularly helpful for operators configuring the system.
4498-4507: Outstanding enhancements to LlamaStackConfiguration and ModelContextProtocolServer.Lines 4498–4507 and 4521–4533 add comprehensive introductory paragraphs with curated external resources. The links to official Llama Stack documentation, Model Context Protocol FAQs, and related Wikipedia articles are well-chosen and significantly enhance developer onboarding.
Also applies to: 4521-4533
4571-4580: Excellent PostgreSQL documentation with practical resources.The PostgreSQL section (lines 4571–4580) now includes context on the Lightspeed Core Stack's use of PostgreSQL and relevant external links (Psycopg, connection strings, Python examples). This provides clear guidance for database configuration.
4721-4757: Comprehensive quota configuration documentation with clear examples.Lines 4721–4757 thoroughly explain quota limiter concepts, configuration options (
period,initial_quota,quota_increase), and two key use cases. The documentation is practical and well-structured.
4883-4898: ServiceConfiguration documentation clearly explains service architecture and options.Lines 4883–4898 provide excellent context on how Lightspeed Core Stack is deployed, worker concurrency, and TLS/CORS configuration. Field descriptions are precise and actionable.
4945-4955: TLSConfiguration section enriched with cryptography context and deployment guidance.Lines 4945–4955 add clear explanations of TLS purpose, use cases (email, VoIP, HTTPS), and curated links to FastAPI deployment, TLS overview, and SSL/TLS learning resources. Significantly improves security-focused documentation.
docs/output.md (1)
3997-4006: Documentation consistency: docs/output.md mirrors docs/openapi.md enhancements with identical quality.Both files contain parallel enhancements to the same sections (CORS, Configuration, Llama Stack, MCP, PostgreSQL, Quotas, Service, TLS). The mirrored documentation is well-structured, informative, and consistently applied across both files.
Also applies to: 4024-4036, 4498-4507, 4521-4533, 4571-4580, 4721-4757, 4883-4898, 4945-4955
| "title": "JSON path", | ||
| "description": "JSONPath expression to evaluate against the JWT payload" | ||
| }, | ||
| "operator": { | ||
| "$ref": "#/components/schemas/JsonPathOperator" | ||
| "$ref": "#/components/schemas/JsonPathOperator", | ||
| "title": "Operator", | ||
| "description": "JSON path comparison operator" | ||
| }, | ||
| "negate": { | ||
| "type": "boolean", | ||
| "title": "Negate", | ||
| "title": "Negate rule", | ||
| "description": "If set to true, the meaning of the rule is negated", | ||
| "default": false | ||
| }, | ||
| "value": { | ||
| "title": "Value" | ||
| "title": "Value", | ||
| "description": "Value to compare against" | ||
| }, | ||
| "roles": { | ||
| "items": { | ||
| "type": "string" | ||
| }, | ||
| "type": "array", | ||
| "title": "Roles" | ||
| "title": "List of roles", | ||
| "description": "Roles to be assigned if the rule matches" | ||
| } |
There was a problem hiding this comment.
JwtRoleRule.value lacks type; many tools will choke
Define allowed types for value (string/number/boolean/array). This improves compatibility with validators/codegen.
"value": {
- "title": "Value",
- "description": "Value to compare against"
+ "title": "Value",
+ "description": "Value to compare against",
+ "anyOf": [
+ { "type": "string" },
+ { "type": "number" },
+ { "type": "boolean" },
+ { "type": "array",
+ "items": {
+ "anyOf": [
+ { "type": "string" },
+ { "type": "number" },
+ { "type": "boolean" }
+ ]
+ }
+ }
+ ]
},📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "title": "JSON path", | |
| "description": "JSONPath expression to evaluate against the JWT payload" | |
| }, | |
| "operator": { | |
| "$ref": "#/components/schemas/JsonPathOperator" | |
| "$ref": "#/components/schemas/JsonPathOperator", | |
| "title": "Operator", | |
| "description": "JSON path comparison operator" | |
| }, | |
| "negate": { | |
| "type": "boolean", | |
| "title": "Negate", | |
| "title": "Negate rule", | |
| "description": "If set to true, the meaning of the rule is negated", | |
| "default": false | |
| }, | |
| "value": { | |
| "title": "Value" | |
| "title": "Value", | |
| "description": "Value to compare against" | |
| }, | |
| "roles": { | |
| "items": { | |
| "type": "string" | |
| }, | |
| "type": "array", | |
| "title": "Roles" | |
| "title": "List of roles", | |
| "description": "Roles to be assigned if the rule matches" | |
| } | |
| "title": "JSON path", | |
| "description": "JSONPath expression to evaluate against the JWT payload" | |
| }, | |
| "operator": { | |
| "$ref": "#/components/schemas/JsonPathOperator", | |
| "title": "Operator", | |
| "description": "JSON path comparison operator" | |
| }, | |
| "negate": { | |
| "type": "boolean", | |
| "title": "Negate rule", | |
| "description": "If set to true, the meaning of the rule is negated", | |
| "default": false | |
| }, | |
| "value": { | |
| "title": "Value", | |
| "description": "Value to compare against", | |
| "anyOf": [ | |
| { "type": "string" }, | |
| { "type": "number" }, | |
| { "type": "boolean" }, | |
| { "type": "array", | |
| "items": { | |
| "anyOf": [ | |
| { "type": "string" }, | |
| { "type": "number" }, | |
| { "type": "boolean" } | |
| ] | |
| } | |
| } | |
| ] | |
| }, | |
| "roles": { | |
| "items": { | |
| "type": "string" | |
| }, | |
| "type": "array", | |
| "title": "List of roles", | |
| "description": "Roles to be assigned if the rule matches" | |
| } |
🤖 Prompt for AI Agents
In docs/openapi.json around lines 5951-5976, the JwtRoleRule.value schema is
missing an explicit type causing validators/codegen to fail; update the "value"
property to explicitly allow string, number, boolean or an array (use oneOf with
"type":"string", "type":"number", "type":"boolean", and "type":"array" with an
items schema for primitive types), keep the existing title/description, and
ensure default/nullability is set consistently if needed so tools can generate
proper types.
1 participant
Description
LCORE-973: updated OpenAPI schema
Type of change
Tools used to create PR
Identify any AI code assistants used in this PR (for transparency and review context)
Related Tickets & Documents
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.