Skip to content

fix(linter): skip the $id check for OpenAPI and OpenRPC service definitions - #49

Open
yingzhehu-TT wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
yingzhehu-TT:fix/lint-skip-id-check-for-service-definitions
Open

fix(linter): skip the $id check for OpenAPI and OpenRPC service definitions#49
yingzhehu-TT wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
yingzhehu-TT:fix/lint-skip-id-check-for-service-definitions

Conversation

@yingzhehu-TT

Copy link
Copy Markdown

Summary

  • Gate the W002 "schema missing $id" warning on a document-type check.
  • Add is_service_definition(): a document declaring a version string under a root
    openapi or openrpc key is a service definition, not a JSON Schema.
  • Add three regression tests: OpenAPI skips the warning, OpenRPC skips the warning,
    and a JSON Schema that merely has a property named openapi still warns.

Motivation

lint_file treats every .json file it is handed as a JSON Schema. OpenAPI and
OpenRPC documents are not JSON Schemas, and neither root object defines $id
so the warning asks authors to add a key their own specification does not permit.

The effect is not cosmetic. On the UCP repository at 7dc6c11:

$ ucp-schema lint --strict source/
✗ 100 files checked: 94 passed, 6 failed (0 errors, 6 warnings)
$ echo $?
1

All six failures are W002, and all six are service definitions:

File Root keys
handlers/tokenization/openapi.json openapi, info, paths
services/payment-actions/embedded.openrpc.json openrpc, info, servers
services/shopping/embedded.openrpc.json openrpc, info, servers
services/shopping/mcp.openrpc.json openrpc, info, servers
services/shopping/permalink.openapi.json openapi, info, servers
services/shopping/rest.openapi.json openapi, info, servers

Zero genuine JSON Schema files in that tree lack $id. So --strict reports a
100% false-positive rate on the UCP source tree, and the flag cannot be adopted
in CI — the one thing it currently blocks on is a warning that does not apply.

Scope

Only the W002 check is gated. $ref resolution, ucp_* annotation checks,
requires checks and the examples conformance check continue to run on service
definitions unchanged — those documents do carry $refs, and a broken one there
is still a real defect worth reporting.

The detection deliberately requires the root value to be a string. A JSON
Schema that describes an OpenAPI document has an openapi property whose value
is a subschema object; that must keep warning, and the third test pins it.

Validation

  • cargo test — full suite passes, including the 3 new tests
    (lint_openapi_service_definition_skips_missing_id_warning,
    lint_openrpc_service_definition_skips_missing_id_warning,
    lint_non_string_openapi_property_still_warns).

  • cargo clippy --all-targets -- -D warnings — clean (exit 0).

  • cargo fmt --check — clean.

  • End-to-end against Universal-Commerce-Protocol/ucp@7dc6c11:

    ucp-schema lint --strict source/
    before (released 1.4.1) exit 1 — 100 checked, 94 passed, 6 failed
    after exit 0100 checked, all passed
  • Non-strict ucp-schema lint source/ output is byte-identical before and after
    apart from the removed warnings, confirming no other behaviour changed.

Follow-up (not in this PR)

With this fixed, ucp-schema lint --strict source/ becomes adoptable in the UCP
repo's CI. That is a natural next step for
.github#21,
but it has to wait for a release carrying this change.

@google-cla

google-cla Bot commented Aug 12, 2026

Copy link
Copy Markdown

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Aug 12, 2026
@yingzhehu-TT

Copy link
Copy Markdown
Author

@googlebot I signed it!

@yingzhehu-TT
yingzhehu-TT force-pushed the fix/lint-skip-id-check-for-service-definitions branch from d2a4a34 to 85603b3 Compare August 12, 2026 08:19
damaz91
damaz91 previously approved these changes Aug 12, 2026
@damaz91
damaz91 dismissed their stale review August 12, 2026 14:15

Needs further review

@damaz91 damaz91 added status:under-review and removed status:needs-triage Signal that the PR is ready for human triage labels Aug 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants