docs: link common types to shared references section (#536)
* docs(specification): centralize shared types per reference.md (#412)
PR #226 made `reference.md` the canonical render destination for all
`types/` schemas (cross-references already resolve there via the
redirect logic in `main.py`). However, capability pages still
re-rendered the same `types/...` field tables inline, leaving three
copies of each shared type (cart.md, checkout.md, catalog/index.md)
alongside the canonical render in reference.md.
This change finishes the centralization:
* `schema_fields(entity, spec)` and `extension_schema_fields(entity,
spec)` now detect when the requested schema lives under a `types/`
directory (common or vertical) and, for any caller other than
`reference.md`, emit a Markdown link to the canonical entry instead
of an inline table.
* `reference.md` continues to render the full tables via
`auto_generate_schema_reference`, so the source of truth is
unchanged.
* Existing capability-page macro calls (`{{ schema_fields('types/
signals', 'cart') }}`, etc.) work unmodified; the surrounding prose
context on each capability page is preserved.
The macro change is intentionally minimal: no `.md` files are touched,
keeping the diff narrow and reversible.
Out of scope (follow-ups):
* wry-ry's suggestion in the issue thread to replace the "Required"
column with a "Visibility" column (`required` / `optional` / `omit`)
is deferred — it needs an `omit` annotation in the schemas which
doesn't exist today. Worth a separate issue once the data model is
agreed.
* scope shared-type consolidation to common/types/
Refines the consolidation pattern introduced for #412. The first pass
redirected every `types/...` reference -- including vertical-namespaced
types like Buyer, Total, Line Item, and Fulfillment Option -- to
reference.md, converting capability pages into runs of "See X in the
Schema Reference" sentences and dropping the operation-filtered variant
tables (Create Request vs. Update Request vs. Response) that integrators
rely on when reading a capability end-to-end.
This commit narrows the redirect to schemas under `common/types/` only.
Cross-vertical primitives -- Pagination, Error Code, Postal Address,
Amount, Link, Media, Message and its variants -- still consolidate to
reference.md, because their fields are not informative inline on a
capability page. Vertical-namespaced types under `<vertical>/types/`
retain their inline render so the variant logic in `_resolve_schema`
keeps producing the correct table for each section.
Render duplication of vertical types across capability pages is
intentional and safe: every render is generated from the same JSON
source via ucp-schema, so drift between them is structurally impossible.
The redirect rule in `create_link` (introduced in #226) is unchanged,
so cross-references emitted from inside any rendered table still target
reference.md and anchor consistency is preserved end-to-end.
Link-sentence count per capability page:
page full-consolidation common-only
---- ------------------ -----------
cart 14 5
checkout 21 8
catalog/index 15 5
fulfillment 12 1
order 7 1
embedded-checkout 6 1
Common-only retains link sentences only for the cross-vertical
primitives each page actually references:
page redirected to reference.md
---- --------------------------
cart Link, Message,
Message Error / Info / Warning
checkout Error Code, Error Response, Link,
Message, Message Error / Info / Warning,
Postal Address
catalog/search Pagination Request / Response *
fulfillment Postal Address
order Postal Address
embedded-checkout Postal Address
* via extension_schema_fields, emitted as a bare cross-ref
rather than a "See X in..." sentence
* drop type-name enumerations from rationale
This commit replaces every type-name list in the docstrings and
inline comments introduced by the previous commit with structural
descriptions (redirect predicate by path, polymorphic-variant
mechanic) and genericized URL shapes. The collision-impossibility
clause in `_resolves_to_shared_type` is rephrased as a stated
assumption rather than a snapshot of the current `common/` directory.
Functional behavior and rendered output are unchanged.
mkdocs build clean; check_links.py validates all internal links. I
Ilya Grigorik committed
1aed32d84f7d792ebdb6af162b730266ea537308
Parent: c861a15
Committed by GitHub <noreply@github.com>
on 6/22/2026, 10:06:36 PM