LCORE-1218: updated config and OpenAPI docs

[tisnik]

Description

LCORE-1218: updated config and OpenAPI docs

Type of change

• Refactor
• New feature
• Bug fix
• CVE fix
• Optimization
• Documentation Update
• Configuration Update
• Bump-up service version
• Bump-up dependent library
• Bump-up library or tool used for development (does not change the final image)
• CI configuration change
• Konflux configuration change
• Unit tests improvement
• Integration tests improvement
• End to end tests improvement
• Benchmarks improvement

Tools used to create PR

• Assisted-by: N/A
• Generated by: N/A

Related Tickets & Documents

• Related Issue #LCORE-1218

Summary by CodeRabbit

• Documentation

  • Clarified configuration descriptions for vector database and URL requirements, specifying HTTP/HTTPS URL validation.

• New Features

  • Added new ConversationTurn and Message models to the API.
  • Added timeout configuration option.
  • Enhanced error reporting with additional context fields.

• Improvements

  • Strengthened URL validation with format enforcement across configuration and documentation endpoints.

[coderabbitai]

Walkthrough

Documentation and schema files were updated with refined descriptions for configuration fields, stricter URL validation constraints (URI format and minLength requirements), and expanded error schema definitions with new context fields.

Changes

Cohort / File(s)	Summary
Configuration description updates docs/config.html, docs/config.md	Updated descriptions: ByokRag.vector_db_id expanded to "Vector database identification," and LlamaStackConfiguration.url extended to specify HTTP/HTTPS URL requirement.
Type and schema refinements docs/config.puml, docs/openapi.json, docs/openapi.md	LlamaStackConfiguration.url type changed to AnyHttpUrl with URI format validation; added minLength and URI format constraints to ReferencedDocument.doc_url; expanded ValidationError schema with input and ctx fields; added ConversationTurn and Message models to OpenAPI documentation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• LCORE-973: configuration options descriptions #854: Modifies LlamaStackConfiguration.url field description and validation requirements.
• LCORE-973: updated OpenAPI schema #857: Updates OpenAPI and documentation for LlamaStackConfiguration.url field enhancements.
• LCORE-973: updated generated doc #865: Touches configuration schema fields including ByokRag.vector_db_id and URL field type/description changes.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main changes: updates to configuration documentation (docs/config.html, docs/config.md, docs/config.puml) and OpenAPI documentation (docs/openapi.json, docs/openapi.md).
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/openapi.json`:
- Around line 6976-6988: The schema for the property titled "Llama Stack URL"
currently allows any URI scheme via "format": "uri" but the description requires
only HTTP/HTTPS; update the schema for "Llama Stack URL" to enforce HTTP/HTTPS
(while still allowing null) by adding a scheme constraint such as a pattern like
^https?:// or an enum/oneOf that limits schemes to http and https (keep the
anyOf null branch intact); modify the schema near the "title": "Llama Stack URL"
entry so validation rejects non-HTTP schemes.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Schema doesn’t enforce HTTP/HTTPS despite the description.

The description says HTTP/HTTPS only, but format: uri allows any scheme. This can let non-HTTP URLs pass schema validation. Consider constraining the scheme to match the description.

🛠️ Suggested schema tightening

                     "url": {
                         "anyOf": [
                             {
                                 "type": "string",
                                 "minLength": 1,
-                                "format": "uri"
+                                "format": "uri",
+                                "pattern": "^https?://"
                             },
                             {
                                 "type": "null"
                             }
                         ],

🤖 Prompt for AI Agents

In `@docs/openapi.json` around lines 6976 - 6988, The schema for the property
titled "Llama Stack URL" currently allows any URI scheme via "format": "uri" but
the description requires only HTTP/HTTPS; update the schema for "Llama Stack
URL" to enforce HTTP/HTTPS (while still allowing null) by adding a scheme
constraint such as a pattern like ^https?:// or an enum/oneOf that limits
schemes to http and https (keep the anyOf null branch intact); modify the schema
near the "title": "Llama Stack URL" entry so validation rejects non-HTTP
schemes.