Skip to content

Refuse an OpenAPI call unsent when it breaks a closed body schema or an enum - #57

Open
tschuehly wants to merge 3 commits into
mainfrom
api-client-validate-args
Open

tschuehly wants to merge 3 commits into
mainfrom
api-client-validate-args

Conversation

@tschuehly

@tschuehly tschuehly commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

An OpenAPI operation call is now checked against the operation's schema before it is sent. A call that breaks the schema is refused, and nothing is sent.

Why

A realm narrows a vendor API by declaring closed write bodies (additionalProperties: false). For example, realm-hubspot's dealUpdate must not set dealstage: a stage move goes only through an operation that needs approval. Today the client ignores the closed schema, so dealUpdate {properties: {dealstage}} reaches HubSpot and moves the deal without approval (embabel-worlds/realm-hubspot#4).

What changes (OpenApiOperationTool)

  • Request body: a property the schema doesn't declare under additionalProperties: false is refused, at any depth. The check follows $ref chains, allOf, oneOf and anyOf, and names the offending path, e.g. properties.dealstage.
  • Path and query values: a value off an enum is refused. Enums match by value, not by string form. A path value is checked as written.
  • Composed bodies: a body the tool composes itself is sent unvalidated, as before.

Live, against HubSpot, the refusal reads "Request body property 'properties.dealstage' is not declared by the operation's schema, which allows no other properties; the request was not sent".

Tests

OpenApiArgumentValidationTest and OpenApiArgumentShapeValidationTest are new. mvn -B -pl embabel-api-client test passes 328 tests.

Not covered (follow-up issues)

Shapes HubSpot doesn't use, tracked in #58:

  • bracketed form field names (payload[secret]) can alias a closed nested object;
  • additionalProperties: false without type is treated as an object, so a valid array is rejected;
  • a whole-array query enum can be bypassed item by item;
  • header enums are not checked.

#31 also edits OpenApiOperationTool (path parameters fail fast), so whichever merges second will need a rebase.

…losed schema forbids or a path or query value off its enum
…h ref chains, compositions and wrong-shaped values, and enums match by value
… sent as, and a closed object's shape, and sends composed bodies unvalidated
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-17T21:27:32.634542Z ab1f6f1 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ab1f6f19ad

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +380 to +386
val name = if (at.isEmpty()) "$key" else "$at.$key"
val declared = resolved.properties?.get(key.toString())
when {
declared != null -> bodyViolation(declared, child, name)
resolved.additionalProperties == false ->
"Request body property '$name' is not declared by the operation's schema, which allows no other properties"
else -> bodyViolation(resolved.additionalProperties as? Schema<*>, child, name)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Validate bracketed form keys against their effective nested paths

For a form-encoded operation with an open root and a closed nested payload object, {"body":{"payload[secret]":"x"}} passes this check because payload[secret] is treated as an unrelated, permitted root property. However, toFormBody emits that key unchanged, so a server using the bracket notation supported by this client's serializer interprets it as payload.secret. This allows a forbidden nested write to reach the server despite the closed schema. Normalize or reject bracketed aliases before validating form bodies.

Useful? React with 👍 / 👎.

Comment on lines +328 to +330
val items = (value as? Collection<*>)?.filterNotNull() ?: listOf(value)
val allowed = (enum == null || enum.any { enumMatches(it, value) } || items.all { v -> enum.any { enumMatches(it, v) } }) &&
(itemEnum == null || items.all { v -> itemEnum.any { enumMatches(it, v) } })

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Match array-valued enums only against the whole array

When a query schema declares an array-valued enum, the item-by-item fallback accepts values outside that enum. For example, with enum: [["a","b"]], input {"q":[["a","b"]]} passes because its single item matches an enum entry, although the supplied outer array does not; {"q":[]} also passes vacuously. resolveQueryParams then sends these inputs instead of refusing them. Keep whole-value enum validation separate from items.enum validation rather than allowing either interpretation to satisfy the same constraint.

Useful? React with 👍 / 👎.

Comment on lines +390 to +391
else -> if (closed) {
"$what is not an object where the operation's schema expects a closed object"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Require an object type before rejecting non-object values

A schema containing properties and additionalProperties: false without type: object does not prohibit arrays or scalars: those keywords constrain object instances only. This branch nevertheless rejects every non-null, non-map value, so previously working requests with valid array or scalar values are now refused locally. It also rejects an explicitly array-typed schema carrying additionalProperties: false. Distinguish an explicitly required object shape from object-specific keywords before issuing this refusal.

Useful? React with 👍 / 👎.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant