Allow sending request fields absent from Discovery (Developer Preview surfaces) — e.g. `--no-validate`

[haizaar]

Summary

gws validates request bodies against the service's public Discovery document. For Google Workspace APIs that have Developer Preview surfaces, that makes gws strictly less capable than the API it wraps: Google documents those request types in the REST reference and the live API accepts them, but they are absent from public Discovery, so gws rejects them locally before anything is sent.

There is currently no way to opt out.

Concrete example — Docs API comments and suggestions

The Docs API's comment/suggestion surface (Developer Preview) includes insertComment, addCommentReply, updateCommentPost, deleteComment, deleteCommentReply, acceptSuggestion, rejectSuggestion, deleteSuggestion, plus writeControl.writeMode = "SUGGEST".

gws refuses all of them. Both of these are real output from gws 0.22.5, with the long "valid properties" list elided:

$ gws docs documents batchUpdate --params '{"documentId":"…"}' \
    --json '{"requests":[{"addCommentReply":{"commentId":"…","post":{"content":"x"}}}]}' --dry-run
error[validation]: Request body failed schema validation:
- requests[0].addCommentReply: Unknown property. Valid properties: ["deleteTableRow", "addDocumentTab", … 40 total …, "deleteFooter"]

$ gws docs documents batchUpdate --params '{"documentId":"…"}' \
    --json '{"requests":[{"insertText":{"location":{"index":1},"text":"x"}}],"writeControl":{"writeMode":"SUGGEST"}}' --dry-run
error[validation]: Request body failed schema validation:
- writeControl.writeMode: Unknown property. Valid properties: ["requiredRevisionId", "targetRevisionId"]

The same requests succeed against docs.googleapis.com over plain HTTPS with the documents scope, on a Cloud project enrolled in the Workspace Developer Preview Program. Verified end to end: addCommentReply posted a reply that is visible in the Docs UI, and writeMode: "SUGGEST" + insertText created a real suggestion which was then read back with suggestionsViewMode=SUGGESTIONS_INLINE and removed with rejectSuggestion.

Why this can't be fixed by configuration

Public Discovery for Docs v1 omits the entire preview surface, via both endpoints, checked today:

Endpoint	revision	Request properties	WriteControl properties
https://www.googleapis.com/discovery/v1/apis/docs/v1/rest	20260812	40	requiredRevisionId, targetRevisionId
https://docs.googleapis.com/$discovery/rest?version=v1	20260812	40	requiredRevisionId, targetRevisionId

None of the 40 Request properties are the preview ones. The labels= query parameter that exposes preview schemas on some Google APIs is accepted but ignored here — labels=DEVELOPER_PREVIEW, labels=PREVIEW and labels=LIMITED_AVAILABILITY all return byte-identical documents (236,739 bytes).

So there is no preview Discovery document to point gws at, and the validation cannot be satisfied by supplying a different schema URL or API version. (--api-version selects v1/v2/v3, not a release channel.)

Request

Any one of these would resolve it:

1. --no-validate (or --skip-validation) — send the body as given and let the API be the authority. Smallest change, keeps validation as the default.
2. --discovery-file <PATH> — override the Discovery document for a call, so a hand-augmented schema can be supplied.
3. Warn instead of erroring on unknown properties, perhaps behind a flag, so unknown fields are forwarded rather than rejected.

(1) looks like the best fit for a CLI whose surface is generated from the API's own description, and it pairs naturally with the existing --dry-run (Validate the request locally without sending it to the API) as its inverse.

Related but distinct: #670 is about reaching services absent from the hardcoded list. This is about fields absent from a listed service's schema — the same "Discovery is the gate" root, but a different gate.

Workaround

A ~370-line Python helper that reads the same authorized_user credentials file gws uses, mints an access token, and POSTs to docs.googleapis.com directly. It works, but it duplicates auth handling and exists only to route around client-side validation — exactly the kind of thing one would rather not maintain alongside gws. It gets deleted the moment either this surface reaches GA or a flag like the above lands.

Environment

• gws 0.22.5 (current latest release)
• Docs API v1, Discovery revision 20260812
• Cloud project enrolled in the Google Workspace Developer Preview Program