[Maxim] adds docs for batched logging api #179
Conversation
📝 WalkthroughSummary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings. WalkthroughThese changes add a new batched logging API specification, introduce voice workflow entity type support across alert and folder schemas, simplify dataset payload structures, enhance parameter nullability in the evaluators API, and comprehensively reorganize the test-run-entries OpenAPI specification with explicit components and refined parameter definitions. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
sammaji
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
public-apis/openapi/folders.json (1)
41-58: Enum inconsistency: VOICE_WORKFLOW and VOICE_WORKFLOW_SIMULATION in schema but absent from request parameters.The Folder.entityType schema (lines 41-58) includes
VOICE_WORKFLOWandVOICE_WORKFLOW_SIMULATION, but these enum values are omitted from POST /v1/folders (lines 124-133), GET /v1/folders (lines 240-249), and GET /v1/folders/contents (lines 386-395). This creates a mismatch where responses can return folders with these types, but API requests cannot create or filter by them. Clarify product intent: should these entity types be supported for folder creation and listing operations?
🧹 Nitpick comments (8)
public-apis/openapi/evaluators.json (1)
63-72: Make limit an integer with bounds; confirm null handling.Use integer semantics for counts and guard invalid values.
Proposed diff:
- "type": "number", - "nullable": true, - "default": 10, + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 100, + "nullable": true, + "default": 10,Please confirm the server treats
limit=nullas “use default/ignore”.public-apis/openapi/datasets.json (2)
228-238: Standardize limit parameters to integer with min/max.Use integer counts and enforce bounds.
Example diff (apply similarly to all shown params):
- "type": "number", - "nullable": true, - "maximum": 100, - "default": 20, + "type": "integer", + "format": "int32", + "minimum": 1, + "maximum": 100, + "nullable": true, + "default": 20,Also applies to: 624-634, 1117-1127
920-931: Response payload now string: document exact encoding or keep typed oneOf.The cell
value.payloadis now a plain string in responses, while requests still use typed text/file objects. Either:
- Document what the string represents (raw text, URL, base64) and add
formatwhere applicable, or- Keep response aligned to request via
oneOfand marknullablewhen needed.Option A (document string and add
formatif URL):- "payload": { - "type": "string" - } + "payload": { + "type": "string", + "description": "Text content or URL/base64 string depending on type", + "format": "uri" + }Option B (align with request shape):
- "payload": { - "type": "string" - } + "payload": { + "oneOf": [ + { "type": "string" }, + { + "type": "object", + "properties": { + "url": { "type": "string", "format": "uri" }, + "base64": { "type": "string" } + } + } + ] + }Also applies to: 1173-1181, 1390-1402
public-apis/openapi/test-run-entries.json (1)
110-163: Tighten filters and sorting shapes (bounds and enums).
- Add
maxItemstofiltersto prevent oversized requests.- Consider
sortenum (e.g.,["asc","desc"]) or a documented format.Example:
- "schema": { + "schema": { "type": "array", + "maxItems": 100, "items": { ... } }public-apis/openapi/batched-logging.json (4)
17-28: Consider top-level security to reduce repetition and satisfy scanners.Define global security so every operation inherits it.
"components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-maxim-api-key", "description": "API key for authentication" } }, "schemas": { ... }, "parameters": {} - }, + }, + "security": [ + { "ApiKeyAuth": [] } + ],
394-404: Bound the batch size to prevent abuse.Add
maxItemstologsto protect the service.- "logs": { - "type": "array", + "logs": { + "type": "array", + "minItems": 1, + "maxItems": 1000, "items": {
703-706: Add URI format to attachment URL for consistency.Trace attachment uses
format: "uri", but span attachment doesn’t.- "url": { - "type": "string", - "description": "URL of the attachment." - }, + "url": { + "type": "string", + "format": "uri", + "description": "URL of the attachment." + },
996-1016: Evaluator arrays: add maxItems to bound per-log evaluation fanout.Helps avoid unexpected evaluation storm.
- "evaluators": { - "type": "array", - "items": { "type": "string" }, - "minItems": 1, + "evaluators": { + "type": "array", + "items": { "type": "string" }, + "minItems": 1, + "maxItems": 50, "description": "Evaluators for the generation. If not provided, the generation will be created without evaluators." },
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
docs.json(1 hunks)public-apis/openapi/alerts.json(1 hunks)public-apis/openapi/batched-logging.json(1 hunks)public-apis/openapi/datasets.json(1 hunks)public-apis/openapi/evaluators.json(1 hunks)public-apis/openapi/folders.json(1 hunks)public-apis/openapi/test-run-entries.json(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**
⚙️ CodeRabbit configuration file
always check the stack if there is one for the current PR. do not give localized reviews for the PR, always see all changes in the light of the whole stack of PRs (if there is a stack, if there is no stack you can continue to make localized suggestions/reviews)
Files:
public-apis/openapi/batched-logging.jsondocs.jsonpublic-apis/openapi/evaluators.jsonpublic-apis/openapi/datasets.jsonpublic-apis/openapi/alerts.jsonpublic-apis/openapi/test-run-entries.jsonpublic-apis/openapi/folders.json
🪛 Checkov (3.2.334)
public-apis/openapi/batched-logging.json
[high] 1-1278: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
[medium] 45-164: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
public-apis/openapi/test-run-entries.json
[medium] 110-158: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
🔇 Additional comments (3)
public-apis/openapi/alerts.json (1)
60-62: LGTM; new VOICE_ alert types added.*Change is consistent with broader VOICE_* support. Keep folder enums in sync (see folders.json comment).
docs.json (1)
747-753: LGTM; API Reference updated for Batched Logging.Entry wiring looks correct.
public-apis/openapi/batched-logging.json (1)
955-970: Ensure discriminator mapping matchesobjectvalues exactly.Mapping looks correct. Keep tests to validate both Chat/Text completion payloads.
| "content": { | ||
| "anyOf": [ | ||
| { | ||
| "type": "string" | ||
| }, | ||
| { | ||
| "type": "array", | ||
| "items": { | ||
| "anyOf": [ | ||
| { | ||
| "type": "object", | ||
| "properties": { | ||
| "type": { | ||
| "type": "string", | ||
| "enum": [ | ||
| "text" | ||
| ], | ||
| "description": "Content type" | ||
| }, | ||
| "text": { | ||
| "type": "string", | ||
| "description": "Text content" | ||
| } | ||
| }, | ||
| "required": [ | ||
| "type", | ||
| "text" | ||
| ], | ||
| "description": "Text content object" | ||
| }, | ||
| { | ||
| "type": "object", | ||
| "properties": { | ||
| "type": { | ||
| "type": "string", | ||
| "enum": [ | ||
| "image_url" | ||
| ], | ||
| "description": "Content type" | ||
| }, | ||
| "image_url": { | ||
| "type": "object", | ||
| "properties": { | ||
| "url": { | ||
| "type": "string", | ||
| "description": "Image URL" | ||
| }, | ||
| "detail": { | ||
| "type": "string", | ||
| "enum": [ | ||
| "auto", | ||
| "low", | ||
| "high" | ||
| ], | ||
| "description": "Image detail level" | ||
| } | ||
| }, | ||
| "required": [ | ||
| "url" | ||
| ], | ||
| "description": "Image URL configuration" | ||
| } | ||
| }, | ||
| "required": [ | ||
| "type", | ||
| "image_url" | ||
| ], | ||
| "description": "Image URL content object" | ||
| } | ||
| ], | ||
| "description": "Content schema" | ||
| } | ||
| }, | ||
| { | ||
| "nullable": true | ||
| } | ||
| ], | ||
| "description": "Message content" | ||
| }, |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
OpenAPI 3.0 nullable keyword anyOf pattern valid
💡 Result:
Short answer: In OpenAPI 3.0 the nullable flag only affects a Schema Object that explicitly declares a type in the same object. That means you cannot rely on nullable to magically apply across composed schemas (anyOf/oneOf/allOf) unless the schema that has nullable also has a type. The pattern keyword works only for string-typed schemas. For nullable + pattern you must put type: string and pattern in the same Schema Object and set nullable: true — or put the string+pattern as one branch of your anyOf/oneOf and make the other branch a schema that allows null, but because OpenAPI 3.0 has no native null type you must use nullable: true on the branch that declares type (or on the parent that declares type). For full null/type-array support upgrade to OpenAPI 3.1. Sources: OpenAPI 3.0 nullable semantics and supported keywords, and guidance on migration to 3.1. [1][2][3]
Examples:
-
Valid (nullable string with pattern):
type: string
pattern: "^[A-Z].*$"
nullable: true
(works because type is declared in same object). [1][3] -
Problematic (attempting to make anyOf branch nullable without type in same object):
anyOf:- $ref: '#/components/schemas/StringWithPattern' # defines type:string + pattern
- $ref: '#/components/schemas/Null' # cannot be type: null in 3.0
In 3.0 you cannot use type: null; nullable must appear on a schema that declares type. Use the parent/branch with type:string + nullable:true instead, or migrate to 3.1. [1][4]
References:
- OpenAPI 3.0 nullable description and rules. [1]
- OpenAPI supported JSON Schema keywords (pattern, type, note that null is handled via nullable). [2]
- OpenAPI 3.1 migration (type arrays / null type introduced). [3]
(If you want, I can show exact YAML examples for a correct anyOf/oneOf pattern + nullable that works in 3.0 and the equivalent 3.1 form.)
🌐 Web query:
OpenAPI 3.0 nullable vs oneOf best practices
💡 Result:
Short answer — for OpenAPI 3.0: use nullable for simple “may be null” cases; use oneOf/anyOf/oneOf for true union/alternative schemas. If you need to represent “$ref or null” or other JSON‑Schema style type arrays, upgrade to OpenAPI 3.1 (which supports type: ['null', ...]) or use careful oneOf/anyOf workarounds.
Guidance and reasons
- OpenAPI 3.0 extends JSON Schema Draft‑05 and does not support "null" as a type; it provides the schema keyword nullable: true for marking a schema as allowing nulls. Use nullable when the intent is simply “this value may be null.” [swagger.io][1][speakeasy-null][2]
- oneOf/anyOf/ allOf are for alternative/combined schemas (true unions, conditional shapes, mutually exclusive variants). Don’t use oneOf just to say “this can be null” — that’s what nullable exists for in 3.0. Use oneOf/anyOf when you need multiple distinct schema choices. [speakeasy-oneof][2]
- Practical note with $ref: OpenAPI 3.0 makes it awkward to express “$ref or null.” Some tooling and validators don’t handle mixing $ref with nullable consistently. In OpenAPI 3.1 you can express null via type arrays or JSON Schema anyOf/oneOf cleanly (e.g., anyOf: [{type: 'null'}, { $ref: '#/components/schemas/Foo' }]) — so upgrade to 3.1 if you need robust union/null patterns. [StackOverflow][3][openapi-upgrade][4]
- Tooling & codegen: many generators and UI tools treat nullable and oneOf differently; using nullable for simple nullability yields simpler generated types. If you plan clients/SDKs or rely on tools, prefer nullable in 3.0 and validate output in your toolchain. [swagger.io][1][speakeasy-null][2]
Recommended checklist
- If field just can be null: use type + nullable: true (OpenAPI 3.0). [1][2]
- If field can be one of several different schemas (not just null): use oneOf/anyOf. [2]
- If you must express "$ref or null" or want JSON‑Schema style unions: upgrade to OpenAPI 3.1 (type arrays / anyOf) or test tool compatibility for 3.0 workarounds. [3][4]
Sources
[1] Supported JSON Schema Keywords — Swagger (OpenAPI 3.0).
[2] Null in OpenAPI / advice on nullable vs oneOf — Speakeasy.
[3] How to specify a property can be null or a reference — Stack Overflow.
[4] Upgrading from OpenAPI 3.0 to 3.1 — OpenAPI docs.
Invalid OAS3.0 schema: {"nullable": true} cannot stand alone as an anyOf option.
In OAS3.0, the nullable keyword only applies to a Schema Object that declares a type in the same object. A standalone {"nullable": true} lacks a type and is invalid. Move nullable: true to the parent content container and list only the concrete types in anyOf:
- "content": {
- "anyOf": [
- { "type": "string" },
- {
- "type": "array",
- "items": { "anyOf": [ /* text | image_url objects */ ] }
- },
- { "nullable": true }
- ],
- "description": "Message content"
- },
+ "content": {
+ "anyOf": [
+ { "type": "string" },
+ {
+ "type": "array",
+ "items": { "anyOf": [ /* text | image_url objects */ ] }
+ }
+ ],
+ "nullable": true,
+ "description": "Message content"
+ },📝 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.
| "content": { | |
| "anyOf": [ | |
| { | |
| "type": "string" | |
| }, | |
| { | |
| "type": "array", | |
| "items": { | |
| "anyOf": [ | |
| { | |
| "type": "object", | |
| "properties": { | |
| "type": { | |
| "type": "string", | |
| "enum": [ | |
| "text" | |
| ], | |
| "description": "Content type" | |
| }, | |
| "text": { | |
| "type": "string", | |
| "description": "Text content" | |
| } | |
| }, | |
| "required": [ | |
| "type", | |
| "text" | |
| ], | |
| "description": "Text content object" | |
| }, | |
| { | |
| "type": "object", | |
| "properties": { | |
| "type": { | |
| "type": "string", | |
| "enum": [ | |
| "image_url" | |
| ], | |
| "description": "Content type" | |
| }, | |
| "image_url": { | |
| "type": "object", | |
| "properties": { | |
| "url": { | |
| "type": "string", | |
| "description": "Image URL" | |
| }, | |
| "detail": { | |
| "type": "string", | |
| "enum": [ | |
| "auto", | |
| "low", | |
| "high" | |
| ], | |
| "description": "Image detail level" | |
| } | |
| }, | |
| "required": [ | |
| "url" | |
| ], | |
| "description": "Image URL configuration" | |
| } | |
| }, | |
| "required": [ | |
| "type", | |
| "image_url" | |
| ], | |
| "description": "Image URL content object" | |
| } | |
| ], | |
| "description": "Content schema" | |
| } | |
| }, | |
| { | |
| "nullable": true | |
| } | |
| ], | |
| "description": "Message content" | |
| }, | |
| "content": { | |
| "anyOf": [ | |
| { | |
| "type": "string" | |
| }, | |
| { | |
| "type": "array", | |
| "items": { | |
| "anyOf": [ | |
| { | |
| "type": "object", | |
| "properties": { | |
| "type": { | |
| "type": "string", | |
| "enum": [ | |
| "text" | |
| ], | |
| "description": "Content type" | |
| }, | |
| "text": { | |
| "type": "string", | |
| "description": "Text content" | |
| } | |
| }, | |
| "required": [ | |
| "type", | |
| "text" | |
| ], | |
| "description": "Text content object" | |
| }, | |
| { | |
| "type": "object", | |
| "properties": { | |
| "type": { | |
| "type": "string", | |
| "enum": [ | |
| "image_url" | |
| ], | |
| "description": "Content type" | |
| }, | |
| "image_url": { | |
| "type": "object", | |
| "properties": { | |
| "url": { | |
| "type": "string", | |
| "description": "Image URL" | |
| }, | |
| "detail": { | |
| "type": "string", | |
| "enum": [ | |
| "auto", | |
| "low", | |
| "high" | |
| ], | |
| "description": "Image detail level" | |
| } | |
| }, | |
| "required": [ | |
| "url" | |
| ], | |
| "description": "Image URL configuration" | |
| } | |
| }, | |
| "required": [ | |
| "type", | |
| "image_url" | |
| ], | |
| "description": "Image URL content object" | |
| } | |
| ], | |
| "description": "Content schema" | |
| } | |
| } | |
| ], | |
| "nullable": true, | |
| "description": "Message content" | |
| }, |
🤖 Prompt for AI Agents
In public-apis/openapi/batched-logging.json around lines 813 to 891 the anyOf
for "content" includes a standalone {"nullable": true} which is invalid in
OAS3.0; remove the standalone nullable entry from the anyOf and instead add
"nullable": true to the parent "content" schema object, leaving only the
concrete type schemas (the "string" option and the "array" option with its
object item schemas) inside anyOf so the schema declares types in the anyOf and
nullability is expressed at the parent level.
| "value": { | ||
| "anyOf": [ | ||
| { | ||
| "type": "string" | ||
| }, | ||
| { | ||
| "type": "number" | ||
| }, | ||
| { | ||
| "nullable": true | ||
| }, | ||
| { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string" | ||
| }, | ||
| { | ||
| "type": "number" | ||
| }, | ||
| { | ||
| "nullable": true | ||
| }, | ||
| { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string" | ||
| }, | ||
| "default": [] | ||
| }, | ||
| { | ||
| "nullable": true | ||
| } | ||
| ] | ||
| }, | ||
| "combinator": { | ||
| "type": "string", | ||
| "enum": [ | ||
| "and", | ||
| "or" | ||
| ], | ||
| "default": "and" | ||
| } | ||
| "default": [] | ||
| }, | ||
| { | ||
| "nullable": true | ||
| } | ||
| ] | ||
| }, |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
OpenAPI 3.0 nullable specification how to use nullable in anyOf oneOf
💡 Result:
Short answer
- In OpenAPI 3.0.x use the nullable flag on a Schema object inside your oneOf/anyOf alternatives (nullable: true). The spec defines nullable as adding "null" to the allowed type when type is set. [1][2]
- In OpenAPI 3.1 (JSON Schema aligned) use an explicit null type (type: 'null' or type: ['null','string'] or oneOf/anyOf including { type: 'null' }). [2]
Examples
OpenAPI 3.0 (recommended way)
components:
schemas:
ValueOrNull:
oneOf:
- type: string
- type: integer
- type: object
nullable: true
Or mark a referenced schema nullable:
components:
schemas:
Foo:
$ref: '#/components/schemas/Bar'
nullable: true
OpenAPI 3.1 (JSON Schema)
components:
schemas:
ValueOrNull:
oneOf:
- type: 'null'
- type: string
Notes and caveats
- 3.0 does not support a native JSON Schema null type; use nullable: true as the standardized approach. Some tools/implementations may allow type: "null" in 3.0 but it is not part of the 3.0 spec. [1][2][4]
- If you need the JSON-Schema-style explicit null handling or toolchain compatibility, prefer OpenAPI 3.1. [2]
Sources
[1] OpenAPI Specification v3.0.3 — Schema Object (nullable).
[2] Swagger / OpenAPI docs — null and data types; OpenAPI 3.1 JSON‑Schema alignment.
[3] Example/tooling notes (oneOf/anyOf nullable usage / SDK behavior).
🏁 Script executed:
cat -n public-apis/openapi/test-run-entries.json | sed -n '115,150p'Repository: maximhq/maxim-docs
Length of output: 1402
🏁 Script executed:
grep -n "nullable" public-apis/openapi/test-run-entries.json | head -20Repository: maximhq/maxim-docs
Length of output: 233
🏁 Script executed:
# Check if this is a reachable/shared schema or if it's inline
cat -n public-apis/openapi/test-run-entries.json | sed -n '100,155p'Repository: maximhq/maxim-docs
Length of output: 2074
🏁 Script executed:
cat -n public-apis/openapi/test-run-entries.json | sed -n '185,195p'Repository: maximhq/maxim-docs
Length of output: 519
Invalid schema: nullable used as a standalone anyOf branch without a type.
In OpenAPI 3.0, nullable is a schema annotation that must be applied to a schema object with a defined type (e.g., {"type": "string", "nullable": true}). Lines 130 and 140 contain bare {"nullable": true} entries with no type, which is invalid per the OpenAPI 3.0 specification and will fail validation.
Remove these duplicate bare nullable entries. To allow null values alongside the defined types (string, number, array), apply nullable: true to the container instead:
"value": {
"anyOf": [
{ "type": "string" },
{ "type": "number" },
- { "nullable": true },
{
"type": "array",
"items": { "type": "string" },
"default": []
}
- { "nullable": true }
],
+ "nullable": true
},📝 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.
| "value": { | |
| "anyOf": [ | |
| { | |
| "type": "string" | |
| }, | |
| { | |
| "type": "number" | |
| }, | |
| { | |
| "nullable": true | |
| }, | |
| { | |
| "type": "array", | |
| "items": { | |
| "type": "string" | |
| }, | |
| { | |
| "type": "number" | |
| }, | |
| { | |
| "nullable": true | |
| }, | |
| { | |
| "type": "array", | |
| "items": { | |
| "type": "string" | |
| }, | |
| "default": [] | |
| }, | |
| { | |
| "nullable": true | |
| } | |
| ] | |
| }, | |
| "combinator": { | |
| "type": "string", | |
| "enum": [ | |
| "and", | |
| "or" | |
| ], | |
| "default": "and" | |
| } | |
| "default": [] | |
| }, | |
| { | |
| "nullable": true | |
| } | |
| ] | |
| }, | |
| "value": { | |
| "anyOf": [ | |
| { | |
| "type": "string" | |
| }, | |
| { | |
| "type": "number" | |
| }, | |
| { | |
| "type": "array", | |
| "items": { | |
| "type": "string" | |
| }, | |
| "default": [] | |
| } | |
| ], | |
| "nullable": true | |
| }, |
🤖 Prompt for AI Agents
In public-apis/openapi/test-run-entries.json around lines 121 to 143: the anyOf
for "value" includes two bare {"nullable": true} branches which are invalid in
OpenAPI 3.0; remove those duplicate bare nullable entries and instead add
"nullable": true to the "value" schema object (or set nullable:true on each
typed branch) so null is allowed alongside string, number and array types,
keeping the array branch and default as-is.
No description provided.