Skip to content

Commit 0579ba0

Browse files
committed
docs: rename refund policy type to return, soften collisions
- Rename the well-known type `dev.ucp.shopping.policy.refund` to `.return`. schema.org models this as MerchantReturnPolicy (return is the head concept; refundType is one outcome facet), so `refund` named the policy after a facet rather than the container. The refund / exchange / credit outcomes live in the type body defined by #257. - Soften the collision rule: a Platform SHOULD (was MUST) flag an authoring collision rather than resolve it silently, treatment left to the Platform. A MUST-surface obligation was inconsistent with policy presentation being optional and had no defined audience. The Business MUST NOT publish a collision is unchanged.
1 parent 4c5a469 commit 0579ba0

2 files changed

Lines changed: 10 additions & 8 deletions

File tree

docs/specification/overview.md

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2254,7 +2254,7 @@ typically versioned and defined alongside their parent capability.
22542254

22552255
## Policies
22562256

2257-
A policy is a business rule — return/refund terms, warranty, subscription
2257+
A policy is a business rule — return terms, warranty, subscription
22582258
terms, and the like — that applies to the items in a response at the time of
22592259
purchase, carried in a core `policies[]` array alongside `messages[]` and
22602260
`links[]`.
@@ -2266,7 +2266,7 @@ A Business publishes well-known and custom policies. Every policy carries a
22662266

22672267
| Well-known type | Description |
22682268
| :-- | :-- |
2269-
| `dev.ucp.shopping.policy.refund` | Return/refund terms. |
2269+
| `dev.ucp.shopping.policy.return` | Return terms. |
22702270
| `dev.ucp.shopping.policy.warranty` | Warranty terms. |
22712271

22722272
A Business **MAY** define custom types in its own domain (e.g.,
@@ -2342,7 +2342,9 @@ To resolve which policy of a given `type` governs a node:
23422342
two overlapping Set matches, or two Response-wide entries of one `type`. This
23432343
is an authoring error, not an artifact of path targeting: naming the node by
23442344
an id would collide the same way. A Business **MUST NOT** publish such a
2345-
collision; a Platform **MUST** surface a warning when it detects one.
2345+
collision. Because resolution is undefined, a Platform **SHOULD** flag the
2346+
ambiguity rather than resolve it silently; the treatment is left to the
2347+
Platform.
23462348

23472349
### Absent vs. empty
23482350

@@ -2383,19 +2385,19 @@ rules apply:
23832385
a `type` no policy covers at that node, the notice still displays, but
23842386
nothing structured stands behind it.
23852387

2386-
For example, an engraved line item is final sale. A response-wide refund policy
2388+
For example, an engraved line item is final sale. A response-wide return policy
23872389
applies to the whole cart, but the item-scoped final-sale policy governs line 2,
23882390
so the disclosure on that line pairs with it — notice and policy agree:
23892391

23902392
<!-- ucp:example schema=shopping/checkout target=$.policies -->
23912393
```json
23922394
[
23932395
{
2394-
"type": "dev.ucp.shopping.policy.refund",
2396+
"type": "dev.ucp.shopping.policy.return",
23952397
"description": { "plain": "Free 30-day returns from delivery." }
23962398
},
23972399
{
2398-
"type": "dev.ucp.shopping.policy.refund",
2400+
"type": "dev.ucp.shopping.policy.return",
23992401
"description": { "plain": "This engraved item is final sale and cannot be returned." },
24002402
"applies_to": ["$.line_items[2]"],
24012403
"url": "https://example.com/returns#final-sale"
@@ -2408,7 +2410,7 @@ so the disclosure on that line pairs with it — notice and policy agree:
24082410
[
24092411
{
24102412
"type": "warning",
2411-
"code": "dev.ucp.shopping.policy.refund",
2413+
"code": "dev.ucp.shopping.policy.return",
24122414
"path": "$.line_items[2]",
24132415
"presentation": "disclosure",
24142416
"content": "This engraved item is final sale and cannot be returned."

source/schemas/shopping/types/policy.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
"properties": {
1313
"type": {
1414
"$ref": "../../common/types/reverse_domain_name.json",
15-
"description": "Policy type discriminator. Open reverse-DNS vocabulary. Well-known values: `dev.ucp.shopping.policy.refund` (return/refund terms), `dev.ucp.shopping.policy.warranty` (warranty terms). Businesses MAY define custom types in their own domain (e.g., `com.example.policy.price_match`). Platforms MUST tolerate unknown values."
15+
"description": "Policy type discriminator. Open reverse-DNS vocabulary. Well-known values: `dev.ucp.shopping.policy.return` (return terms), `dev.ucp.shopping.policy.warranty` (warranty terms). Businesses MAY define custom types in their own domain (e.g., `com.example.policy.price_match`). Platforms MUST tolerate unknown values."
1616
},
1717
"description": {
1818
"$ref": "../../common/types/description.json",

0 commit comments

Comments
 (0)