# The Shabbat Policy Standard — `/.well-known/shabbat-policy.json`

An open, machine-readable way for any website to declare what it does during
Shabbat and Jewish holidays. Publish one JSON file at
`https://YOURSITE/.well-known/shabbat-policy.json` and Shabbat-aware tools — like
the **ShabbatCloud browser extension** — can read it and show shoppers a
**"Verified Shabbat-aware"** signal. ShabbatCloud.com generates this file
automatically for its customers; any site may adopt it for free.

This is a transparency standard, not a halachic ruling. It states what your
systems do; it does not certify observance.

## Schema (version 1)

| Field | Type | Notes |
|---|---|---|
| `version` | number | Schema version. Currently `1`. |
| `shabbatAware` | boolean | `true` if the site governs sensitive activity for Shabbat/holidays. |
| `provider` | string? | e.g. `"shabbatcloud"`, or `"self"` if self-declared. |
| `behavior` | object? | Per-system behavior. Keys are free-form system names (`checkout`, `orders`, `payments`, `support`, `shipping`, `crm`, `release`, …). |
| `holidays` | boolean? | `true` if the policy also applies to Jewish holidays (Yom Tov). |
| `timezone` | string? | IANA timezone used to evaluate the Shabbat window (e.g. `"Asia/Jerusalem"`). |
| `kashrut` | object? | `{ "certified": boolean, "agency": string, "verifyUrl": string }` — a *claimed* certification + where to verify it. |
| `statement` | string? | A short human-readable statement shown to users. |
| `policyUrl` | string? | A link to your full, human-readable policy. |
| `updated` | string? | ISO date (`YYYY-MM-DD`) the policy was last updated. |

### Allowed `behavior.*` values
`allow` · `read-only` · `queue` · `deferred` · `delayed` · `held` · `paused` ·
`routed` · `post-havdalah`

These mirror the decisions a Shabbat policy engine makes per action: keep it
available, make it read-only, queue it, defer/delay it, hold it, pause it, route
it elsewhere, or release it after Havdalah.

## Example

```json
{
  "version": 1,
  "shabbatAware": true,
  "provider": "shabbatcloud",
  "behavior": {
    "checkout": "deferred",
    "orders": "held",
    "payments": "deferred",
    "support": "paused",
    "shipping": "paused",
    "release": "post-havdalah"
  },
  "holidays": true,
  "timezone": "Asia/Jerusalem",
  "kashrut": { "certified": true, "agency": "OU", "verifyUrl": "https://oukosher.org" },
  "statement": "We pause sensitive business activity for Shabbat and chagim.",
  "policyUrl": "https://example.com/shabbat",
  "updated": "2026-06-27"
}
```

## How to adopt
1. Create the file above and host it at `/.well-known/shabbat-policy.json` (served as `application/json`, publicly readable).
2. Keep `updated` current when your policy changes.
3. Optionally add a `<meta name="shabbat-policy" content="/.well-known/shabbat-policy.json">` tag so tools can discover it from the page too.

ShabbatCloud.com publishes its own policy at
[`/.well-known/shabbat-policy.json`](/.well-known/shabbat-policy.json) as the
reference implementation.

> ShabbatCloud provides technology and operational controls to help businesses
> implement their Shabbat and holiday policies. This standard is informational and
> does not replace personal halachic guidance.