[Eliza Farley (elizafarley)]

Why

A customer team built on TabularDataByFilter instead of TabularDataByMQL. The proto has marked TabularDataByFilter deprecated since November 2024, but the generator never read that flag. So the data client reference showed it as an ordinary method, listed in the summary table above MQL with no warning. An audit found the same gap for five more deprecated RPCs.

What changed

Generator support for deprecation notes (update_sdk_methods.py)
The protos don't say what replaces a deprecated method, so the replacement is named in a hand-written override, static/include/<type>/apis/overrides/protos/<resource>.<Proto>.deprecated.md. When that file exists, the method gets a "Deprecated" caution alert above its description, and its summary-table row reads Deprecated. followed by the note's first sentence. I also moved the table's first-sentence extraction into a helper, override_first_sentence(), so the description and the note share it. Behavior for existing overrides is unchanged.

How to find new deprecations (CLAUDE.md, "Generated SDK reference docs")
The convention for .deprecated.md notes, a grep that lists deprecated RPCs in viamrobotics/api, and the regeneration caveats below. An earlier version of this PR included an audit script. It was dropped in review in favor of the grep.

Deprecation notes added. Each replacement comes from the app server's deprecation comments and error messages in viamrobotics/app, under domains/datamanagement/:

Method	Note
TabularDataByFilter	Use TabularDataByMQL/TabularDataBySQL, or ExportTabularData to stream all data from one source.
AddTagsToBinaryDataByFilter	Use AddTagsToBinaryDataByIDs. The server already returns an unimplemented error for this method.
RemoveTagsFromBinaryDataByFilter	Use RemoveTagsFromBinaryDataByIDs. The server already returns an unimplemented error for this method.
TagsByFilter	The server returns tags from both binary and tabular data (tags_by_filter.go). Collect them from BinaryDataByFilter (metadata.capture_metadata.tags) and from the readings table's tags field with TabularDataByMQL.
BoundingBoxLabelsByFilter	The server reads binary annotations only. Use BinaryDataByFilter and collect label from metadata.annotations.bboxes.
Motion GetPose	Use the machine client's GetPose. This moves the existing deprecation sentence out of the description and into the alert, so the table shows it too.

Regenerated the data and motion reference pages. The diff contains only the deprecation additions. Documented in CLAUDE.md two ways a manual regeneration silently drops content: running an app resource without app, and an unreachable SDK docs site. Fixed one line in the frame system page that pointed to motion GetPose.

Audit results

No hand-written page recommends TabularDataByFilter, so the reference page was the only place the docs steered readers to it. The other hits were false positives, which I checked one by one:

• every robot GetStatus hit is the generic service's GetStatus, which isn't deprecated
• fields like binary_ids and binary_id match SDK parameters that now take ID strings
• sensor_names and mime_type match config attributes and camera parameters

Not in this PR

• Three tutorials still call motion_service.get_pose: claw-game.md, constrain-motion.md and plan-motion-with-arm-gripper.md. These are code rewrites that should be tested on a machine.

Checks

prettier 3.2.5, markdownlint, vale 3.12.0 (including CLAUDE.md and the changed static/ Markdown), scripts/frontmatter_rules.py and make build-prod all pass. I confirmed the alert renders on /reference/apis/data-client/.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	1962649
🔍 Latest deploy log	https://app.netlify.com/projects/viam-docs/deploys/6adbb39e621acba666a820cb
😎 Deploy Preview	https://deploy-preview-5457--viam-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 32 (🔴 down 9 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (no change from production) PWA: 60 (no change from production) View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Jeremy Rose (jeremyrose-viam)]

Thanks for this. The deprecation notes fix a real gap, and the sidecar plus table prefix is a good way to surface a deprecation early on the page. The audit was useful too. I have a few suggestions.

1. Drop check_deprecated_protos.py from this PR, and use a periodic manual check instead.

It's 356 lines, with a hand-rolled proto parser and a hardcoded resource map that will drift from update_sdk_methods.py. A newly deprecated RPC is rare enough that this tooling costs more to maintain than the gap it closes. --strict also isn't wired into CI, so nothing enforces it, and in practice it would be run by hand anyway.

A grep run every month or so gives the same result with nothing to maintain:

git clone --depth 1 https://github.com/viamrobotics/api /tmp/api
grep -rnE "^    option deprecated = true;" /tmp/api/proto

This lists deprecated RPCs only (14 today), which keeps the read short. Compare the hits against the .deprecated.md files under static/include/*/apis/overrides/protos/. Anything documented in the reference without a note gets one. Today, the six documented ones (five data methods and motion GetPose) all have notes, so this reproduces the script's finding. The filter relies on the api repo's indentation, so the broader grep -rn "deprecated = true" is the fallback. It also shows deprecated fields and messages, about 100 hits.

Could you add the convention and the cadence to the "Generated SDK reference docs" section of CLAUDE.md? Something like: "When viamrobotics/api marks an RPC deprecated, add a .deprecated.md note naming the replacement. Check for new deprecations monthly with the grep above." That reaches anyone working in the repo. If this ever recurs often enough to be annoying, a small buf-based check in check-methods.yml can replace the manual step.

2. Source the removal claims.

TabularDataByFilter.deprecated.md says it "will be removed in a future release". The PR description only cites a removal plan for TagsByFilter and BoundingBoxLabelsByFilter. Can we confirm that TabularDataByFilter is slated for removal, and that the owning team is comfortable with us saying so publicly? If not, I'd drop that sentence from the note.

3. Verify the replacement wording for TagsByFilter and BoundingBoxLabelsByFilter.

The notes say to collect unique values from each BinaryDataByFilter result's "capture metadata" and "bounding box annotations". Could you confirm those are the right field names in the response?

4. Persist the regeneration caveats.

The notes in the PR description about including app when regenerating data, and the partial output when an SDK docs site is unreachable, are useful. They'll be lost after merge. A short comment in update_sdk_methods.py or a CLAUDE.md line would keep them.

[Eliza Farley (elizafarley)]

Jeremy Rose (@jeremyrose-viam) thanks, all four are addressed in 1962649.

1. Audit script dropped. check_deprecated_protos.py is removed. The "Generated SDK reference docs" section of CLAUDE.md now documents the .deprecated.md convention and how to list deprecated RPCs. I adjusted your grep to print RPC names instead of bare line numbers:

grep -rn -B2 "^    option deprecated = true;" /tmp/api/proto | grep " rpc "

It returns the same 14 RPCs, and the broader grep -rn "deprecated = true" is noted as the fallback. I'm still deciding how to run it regularly: a monthly manual check, or a lightweight automated reminder. I'll add the cadence line to CLAUDE.md once that's settled.

2. Removal claims dropped. No note says "will be removed" anymore. They say the method is deprecated and name the replacement. I also added a line to CLAUDE.md: don't claim removal plans unless the owning team has said so publicly.

3. Verified against the code, which corrected one note.

• TagsByFilter returns the unique tags from both binary and tabular data (domains/datamanagement/tags_by_filter.go in viamrobotics/app), so pointing only at BinaryDataByFilter would have missed tabular tags. The note now covers both: metadata.capture_metadata.tags on BinaryDataByFilter results, and the tags field of the readings table through TabularDataByMQL. The server reads the same tags field, and /data/schema/ documents it.
• BoundingBoxLabelsByFilter reads binary annotations only, so BinaryDataByFilter fully replaces it. The note now names the exact field: label on metadata.annotations.bboxes.

The field paths come from the BinaryDataByFilterResponse → BinaryData → BinaryMetadata messages in data.proto.

4. Regeneration caveats saved. They're in the same CLAUDE.md section:

• include app when regenerating any app resource, or every Go tab drops
• an unreachable SDK docs site still produces output, without that SDK's tabs, and the script exits 0

Data reference regenerated cleanly, and make build-prod and vale (including CLAUDE.md) pass.

[github-actions]

🔎💬 Inkeep AI search and chat service is syncing content for source 'Viam Docs'