feat(vtex): add schema parameter to Masterdata loaders and actions

[pedrobernardina]

Some VTEX Masterdata queries were failing because the corresponding loaders and actions in DecoCX did not receive the required schema parameter. Without explicitly passing the schema, certain endpoints fall back to defaults that do not match our use cases, resulting in inconsistent behavior or empty responses.

This PR adds support for an optional schema parameter across all VTEX Masterdata loaders and actions. When provided, the value is forwarded to the underlying Masterdata client, ensuring that schema-specific queries work as expected.

Changes

• Added optional schema argument to Masterdata loaders and actions
• Forwarded the parameter to the VTEX Masterdata API calls
• Updated interfaces and typings accordingly
• Added minimal safety checks to maintain backward compatibility

Why this is needed

Some Masterdata data sources rely on custom schemas. Without the schema parameter, those queries silently fail or return incomplete results. Explicit schema forwarding ensures correct resolution and aligns the integration with VTEX API requirements.

Summary by CodeRabbit

• New Features

  • Document create, update, and search operations now accept an optional _schema parameter so requests include a specified data-entity schema when provided.

• Documentation

  • API documentation expanded with new schema/query parameter declarations and richer request/response examples for data-entity and session-related endpoints.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds an optional schema?: string prop to MasterData create, update, and search flows (threaded as _schema in request payloads), updates the client types for POST documents to accept _schema in searchParams, and extends OpenAPI declarations / JSON with _schema on several dataentity endpoints and added schema definitions.

Changes

Cohort / File(s)	Summary
MasterData Action Methods vtex/actions/masterdata/createDocument.ts, vtex/actions/masterdata/updateDocument.ts	Added optional schema?: string to Props; destructure schema and include _schema: schema in POST/PATCH payloads for create/update code paths.
MasterData Loader vtex/loaders/masterdata/searchDocuments.ts	Added optional schema?: string to Props; include _schema in masterdata search API request when provided.
Client Type Definitions vtex/utils/client.ts	Updated POST /api/dataentities/:acronym/documents endpoint type to include searchParams: { _schema?: string }.
OpenAPI Generated Types vtex/utils/openapi/vcs.openapi.gen.ts, vtex/utils/openapi/vcs.openapi.json	Declared _schema?: string in searchParams for multiple dataentity endpoints (POST/PUT/PATCH/GET/DELETE/search) and added numerous schema definitions/examples in the OpenAPI JSON.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Review wiring of schema → _schema in all payloads and conditional inclusion.
• Verify vtex/utils/client.ts type change aligns with runtime usage.
• Inspect vcs.openapi.gen.ts / vcs.openapi.json additions for unintended edits or large autogenerated diffs.

Poem

🐇 I nibble at code with whiskers twitching bright,

A tiny _schema tucked in just right,
Optional, polite, it hops through each call,
Create, update, search — I placed it all,
A carrot of order in the moonlit byte 🥕

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description covers the motivation, changes made, and reasoning, but is missing the Issue Link and Loom Video sections required by the template.	Add Issue Link (with #ISSUE_NUMBER and link) and Loom Video sections as specified in the template to complete the description.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change—adding schema parameter support to Masterdata loaders and actions—which aligns with the changeset across multiple files.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

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

[github-actions]

Tagging Options

Should a new tag be published when this PR is merged?

• 👍 for Patch 0.133.21 update
• 🎉 for Minor 0.134.0 update
• 🚀 for Major 1.0.0 update

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 05e5834 and b5d2b63.

📒 Files selected for processing (4)

• vtex/actions/masterdata/createDocument.ts (3 hunks)
• vtex/actions/masterdata/updateDocument.ts (3 hunks)
• vtex/loaders/masterdata/searchDocuments.ts (3 hunks)
• vtex/utils/client.ts (1 hunks)

🧰 Additional context used

🪛 GitHub Actions: ci

vtex/actions/masterdata/updateDocument.ts

[error] 43-43: TS2353: Object literal may only specify known properties, and '_schema' does not exist in type '{ acronym: URLPatternParam; }'.

---

[error] 47-47: TS2353: Object literal may only specify known properties, and '_schema' does not exist in type '{ acronym: URLPatternParam; } & { id: URLPatternParam; }'.

vtex/loaders/masterdata/searchDocuments.ts

[error] 63-63: TS2353: Object literal may only specify known properties, and '_schema' does not exist in type '{ acronym: URLPatternParam; } & { _fields?: string | undefined; _where?: string | undefined; _sort?: string | undefined; }'.

vtex/actions/masterdata/createDocument.ts

[error] 39-39: TS2353: Object literal may only specify known properties, and '_schema' does not exist in type '{ acronym: URLPatternParam; }'.

🔇 Additional comments (5)

vtex/actions/masterdata/updateDocument.ts (1)

5-14: Optional schema prop wiring looks correct

Adding schema?: string to Props and threading it through the destructuring keeps the action backwards compatible while exposing schema selection where needed. No issues here.

Also applies to: 28-29

vtex/loaders/masterdata/searchDocuments.ts (2)

19-22: schema prop and documentation are consistent with Masterdata usage

The new optional schema field on Props plus its description look good and align with VTEX Masterdata’s _schema query parameter. No changes needed here.

---

54-64: Verify that _schema is not a valid parameter for the search endpoint and that TS2353 error occurs

The proposed fix assumes the route's type signature excludes _schema, causing excess property check failures. Verify this is the actual type definition and that the conditional approach suggested (creating baseParams and conditionally spreading _schema) is the correct fix rather than updating the route type definition itself.

vtex/utils/client.ts (1)

291-297: _schema searchParams mapping for POST documents is aligned with new behavior

Adding an optional _schema under searchParams for "POST /api/dataentities/:acronym/documents" matches the new schema support while remaining backwards compatible for existing callers that don’t set it. Looks good; just ensure this interface corresponds to the client actually used for Masterdata document creation.

vtex/actions/masterdata/createDocument.ts (1)

5-10: Optional schema on create props is safe and consistent

Exposing schema?: string on Props and threading it through the destructuring is backwards compatible and consistent with the other Masterdata operations.

Also applies to: 24-25

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (3)

vtex/loaders/masterdata/searchDocuments.ts (1)

19-22: LGTM! Optional enhancement: consider expanding documentation.

The addition of the optional schema parameter is implemented correctly and maintains backward compatibility.

For improved developer experience, consider adding more context to the JSDoc:

 /**
-  * @description Schema of the data entity.
+  * @description Schema name for the data entity. Use this when querying a specific schema version or custom schema. If not provided, the default schema is used.
  */
 schema?: string;

vtex/utils/openapi/vcs.openapi.gen.ts (1)

868-873: JSDoc for _schema parameter is inaccurate on five endpoints

The reused JSDoc stating "This field is required when using _where or _fields query parameters" appears on endpoints that don't expose those parameters:

• POST /api/dataentities/:acronym/documents (line 868)
• PATCH /api/dataentities/:acronym/documents (line 903)
• PUT /api/dataentities/:acronym/documents/:id (line 998)
• DELETE /api/dataentities/:acronym/documents/:id (line 1032)
• PATCH /api/dataentities/:acronym/documents/:id (line 1059)

Only GET /api/dataentities/:acronym/documents/:id actually includes _fields in its searchParams, where the JSDoc is partially justified. Clarify the documentation to either remove the conditional reference on endpoints that don't expose these parameters, or rephrase generically. Correct this in the OpenAPI source or generator rather than in the generated TypeScript.

vtex/utils/openapi/vcs.openapi.json (1)

974-984: Clarify the required field: parameter is conditionally required but marked required: false.

The parameter description states: "This field is required when using _where or _fields query parameters," yet it's marked as required: false. This creates ambiguity for API consumers about when the parameter is actually mandatory.

OpenAPI does not natively support conditional required fields. Consider one of these approaches:

1. Update the description to explicitly state when the parameter is optional vs. required at the schema documentation level.
2. Mark as required: true if the parameter should always be provided for proper schema resolution.
3. Document in prose (outside the spec) that the parameter is strongly recommended for _where/_fields queries to avoid endpoint fallbacks.

Clarify the intent and update the parameter definition and/or documentation accordingly.

Also applies to: 1572-1582

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 94d5de5 and 2564730.

📒 Files selected for processing (6)

• vtex/actions/masterdata/createDocument.ts (3 hunks)
• vtex/actions/masterdata/updateDocument.ts (3 hunks)
• vtex/loaders/masterdata/searchDocuments.ts (3 hunks)
• vtex/utils/client.ts (1 hunks)
• vtex/utils/openapi/vcs.openapi.gen.ts (7 hunks)
• vtex/utils/openapi/vcs.openapi.json (7 hunks)

🚧 Files skipped from review as they are similar to previous changes (3)

• vtex/actions/masterdata/createDocument.ts
• vtex/utils/client.ts
• vtex/actions/masterdata/updateDocument.ts

🔇 Additional comments (2)

vtex/loaders/masterdata/searchDocuments.ts (1)

54-54: No action required. The HTTP client implementation in utils/http.ts (lines 201-202) explicitly filters out undefined values before constructing the URL search parameters, so _schema: undefined never reaches the VTEX API.

vtex/utils/openapi/vcs.openapi.gen.ts (1)

733-751: GET search: _schema query param addition looks correct

The new optional _schema?: string in searchParams for "GET /api/dataentities/:acronym/search" is consistent with Master Data v1 usage and the JSDoc matches the presence of _where and _fields. This should unblock schema-aware search callers without breaking existing ones.