Skip to content

ci: fail the docs build on schema tables that rendered wrong - #1007

Closed
sakinaroufid wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
sakinaroufid:ci/check-rendered-tables
Closed

sakinaroufid wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
sakinaroufid:ci/check-rendered-tables

Conversation

@sakinaroufid

Copy link
Copy Markdown
Contributor

Description

Adds a post-build check for the generated field tables and wires it into docs.yml after check_links.py.

Background: #352, #465, #549, #552, #894 were all the same bug class. _render_table_from_schema couldn't name a type, so the Type cell came out as any / OneOf[] / Array[any] / blank, and the build was green. #784 is the headers-table version of it. All of those were caught by reading the published page, and all the fixes pinned the specific path in test_schema_tables.py, which is fine but doesn't help with the next path.

check_rendered_tables.py parses the built html (local_preview or site) and fails on:

  • a Name|Type|Requirement|Description table row with Type empty, any, *[any], *[] or containing {/}
  • a specification/**/rest/index.html page with no Header|Required|Description table
  • a response_*_schema def in ucp.json with no ucp-response-*-schema id anywhere in the site

Matching on the exact macro header keeps it off the hand-written tables (payment/template.md has {type} cells on purpose, a few enum tables have a Type column with lowercase values). mike's redirect pages are skipped by title.

Running it on main found a live one. amenity_type.json is only a $ref to reverse_domain_name.json, which is a string+pattern. The elif "$ref" in schema_data branch appended the ref's output under the table header, the ref rendered as prose (description + Pattern:), and python-markdown treats a non-blank line after the separator row as a table row. Result: on location/rest, location/mcp and reference.md the Amenity Type section is a 4-col table with the whole description sitting in the Name column. The change in main.py returns the body on its own when it isn't table rows. Reverse Domain Name on reference.md already renders that way. Test added.

Pre-commit runs test_check_rendered_tables.py on changes to the two scripts, same pattern as the other script tests. AGENTS.md lists the command next to check_links.

Not covered: anything the check doesn't know to look for. It's a tripwire for the shapes we've already been bitten by, not a schema-vs-table diff.

Category (Required)

  • Core Protocol
  • Governance/Contributing
  • Capability
  • Documentation
  • Infrastructure: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
  • Maintenance
  • SDK
  • Samples / Conformance
  • UCP Schema
  • Community Health (.github)

Related Issues

#352 #465 #549 #552 #784 #894

Checklist

  • I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
  • I have updated the documentation (if applicable).
  • My changes pass all local linting and formatting checks.
  • I have added tests that prove my fix is effective or that my feature works.
  • New and existing unit tests pass locally with my changes.
  • (For Core/Capability) I have included/updated the relevant JSON schemas.
  • I have regenerated Python Pydantic models by running generate_models.sh under python_sdk.

Screenshots / Logs (if applicable)

main, without the main.py change:

$ uv run python scripts/check_rendered_tables.py local_preview
local_preview/draft/specification/common/location/mcp/index.html: field 'Reverse-domain identifier used for collision-safe namespacin...' rendered with type ''
local_preview/draft/specification/common/location/rest/index.html: field 'Reverse-domain identifier used for collision-safe namespacin...' rendered with type ''
local_preview/draft/specification/reference/index.html: field 'Reverse-domain identifier used for collision-safe namespacin...' rendered with type ''

3 rendering problem(s) found

this branch:

$ uv run python scripts/check_rendered_tables.py local_preview
Rendered tables OK
$ uv run python scripts/test_schema_tables.py | tail -1
18 passed, 0 failed
$ uv run python scripts/test_check_rendered_tables.py | tail -1
16 passed, 0 failed

The field tables on the spec pages are generated from the schemas and
OpenAPI documents. When the macro cannot name a type, the build still
succeeds and the cell reads "any", "OneOf[]", "Array[any]" or nothing.
That has reached the published site five times (Universal-Commerce-Protocol#352, Universal-Commerce-Protocol#465, Universal-Commerce-Protocol#549, Universal-Commerce-Protocol#552,
Universal-Commerce-Protocol#894), each found by someone reading the page, and the Location REST
binding shipped without its headers table the same way (Universal-Commerce-Protocol#784). Every
fix added a test for the case it found; nothing checked the next one.

Add scripts/check_rendered_tables.py and run it after the build in
both verify jobs, next to check_links.py. Over the built HTML it
asserts that every Name / Type / Requirement / Description table has
a named type in each row, that every REST binding page renders its
HTTP Headers table, and that every response_*_schema definition in
ucp.json has a rendered section. Hand-written tables with other
headers are left alone. Unit tests run from pre-commit like the other
script tests.

The first run against main found a live case: amenity_type.json is a
$ref to reverse_domain_name.json, a string with a pattern. The macro
emitted the table header and then the type's prose, which Markdown
read as a one-cell row with an empty Type, on the location REST and
MCP pages and the reference page. A $ref that resolves to prose is now
returned without the header, so Amenity Type renders like Reverse
Domain Name does. The macro tests pin it.

Verified: full draft build, check_links and the new check pass;
test_schema_tables 18 passed; test_check_rendered_tables 16 passed.
@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Oct 29, 2026
@sakinaroufid

Copy link
Copy Markdown
Contributor Author

Splitting this up. The test vectors and the signed-example verification have moved to #1008, rebased onto current main and extended to cover every inline example on the spec pages, not only the vectors section. That part is Infrastructure/Documentation and can go through maintainer review on its own.

The two normative changes here, the order webhook delivery contract and the ready_for_complete definition for checkout, need Tech Council review and will each get a separate PR once #1008 lands, so their diffs show only the rule change. Leaving this open until then as the reference for those two.

@sakinaroufid

Copy link
Copy Markdown
Contributor Author

nvm - decided to close this in favour of #1008, which carries the test vectors rebased on main and extends verification to every signed example in the spec. The order webhook delivery contract and the ready_for_complete definition from this branch are normative changes and will be opened as separate PRs for Tech Council review (upon request)

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

Labels

status:needs-triage Signal that the PR is ready for human triage

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants