local-storefront 0.2.0 → 0.3.0-rc.1

package/docs/data-format.md

@@ -0,0 +1,943 @@
+# Store data format
+
+local-storefront renders a Shopify theme from JSON files instead of the Shopify API. This
+document describes those files. It is printed by `npx local-storefront docs`, and
+`npx local-storefront init` writes it next to the data as `README.md`.
+
+The format is strict on purpose: unknown fields, wrong types and broken references are errors.
+An unknown field is left out, and the rest of its file is still read.
+Run `npx local-storefront validate` after every change. Each problem is reported with a code,
+the file, a JSON pointer to the value, and usually a hint:
+
+```text
+error[unknown_field]: unknown field "titel"
+  --> products/shirt.json at /titel
+  hint: did you mean "title"?
+```
+
+`npx local-storefront validate --format json` prints the same report as JSON, for tools and
+LLMs:
+
+```json
+{
+  "ok": false,
+  "errors": 1,
+  "warnings": 0,
+  "data": "./shopify-local",
+  "diagnostics": [
+    {
+      "severity": "error",
+      "code": "unknown_field",
+      "file": "products/shirt.json",
+      "path": "/titel",
+      "message": "unknown field \"titel\"",
+      "hint": "did you mean \"title\"?"
+    }
+  ],
+  "app": null
+}
+```
+
+The exit status is `0` when the data is valid and `1` when it has errors. Warnings do not fail.
+
+## The data directory
+
+By default the data is read from `shopify-local/` inside the theme. Pass `--data <dir>` (or
+set `LSF_DATA`) to use another directory. Without any data directory, a built-in demo store is
+used; `npx local-storefront init` writes that demo store to disk as a starting point.
+
+```text
+shopify-local/
+  store.json            data files: any name, any number, merged together
+  menus.json
+  products/             one product per file; the file name is the default handle
+    blue-shirt.json
+  collections/          same for collections,
+  pages/                pages,
+  blogs/                blogs (with their articles),
+  customers/            customers,
+  menus/                and menus (the file name is the menu handle)
+  checkouts/            checkout scenarios, one named setup of the local checkout per file
+  files/                images, videos, fonts: served under /cdn/shop/files/
+  schema/               JSON Schemas for editors, written by `init` (not read back)
+  README.md             this document
+```
+
+**Starting from your own data.** The files of the demo store name each other:
+`collections.json`, `menus.json` and the `selling_plan_groups` of `store.json` name its
+products, `menus.json` names its pages and its blog, and `gift_cards.json` names a product and
+a customer. Replace `products/` and `customers.json` with yours, and edit `collections.json`
+and `menus.json`. Delete what you don't need: `gift_cards.json`, the `selling_plan_groups` of
+`store.json`. Then run `npx local-storefront validate`: each name left over is an error
+(`unknown_product`, `unknown_reference`, `unknown_customer`) with its file and pointer. Keep
+`schema/`, for your editor.
+
+No error points at the rest of the demo content, so replace it too: the shop's name in
+`store.json` (`Local Supply Co.`), the pages of `pages.json` and the articles of `blogs.json`
+(or delete them, with their links in `menus.json`). The demo's automated
+[collections](#collections) pick products by `type` and by the tag `sale`: give yours a `type`
+and `tags`, or these collections stay empty.
+
+Every `*.json` file at the root is a **data file**: an object with any of the keys `shop`,
+`products`, `collections`, `pages`, `blogs`, `menus`, `customers`, `companies`, `gift_cards`,
+`selling_plan_groups`, `locations`, `swatches`, `metaobjects`, `localization`, `files`,
+`session`, `checkout`, `now`, `theme_settings` and `app`. Root files are merged, so the data can be
+split however is convenient. Lists add up; `shop`, `localization`, `session`, `checkout` and
+`now` may be defined in one file only.
+
+A file in `products/`, `collections/`, `pages/`, `blogs/` or `customers/` holds one entity, or
+an array of them. Files are read in alphabetical order, which is the order products matched by
+the rules of an automated collection are listed in.
+
+JSON files may contain `//` and `/* */` comments.
+
+### Editor support
+
+Point `$schema` at the schema of the file's kind to get completion and inline errors:
+
+```json
+{ "$schema": "../schema/product.schema.json", "title": "Blue shirt", "price": "19.99" }
+```
+
+`npx local-storefront schema <kind>` prints a schema (`store`, `product`, `collection`, `page`,
+`blog`, `customer`, `menu`, `session`, `checkout-scenario`), `npx local-storefront schema --out <dir>` writes them
+all, and a running server serves them at `/__lsf/schema/<kind>`.
+
+## Conventions
+
+- **Unknown fields are errors.** A typo never silently does nothing.
+- **Ids and handles are optional.** A handle is derived from the title (`"Blue Shirt"` →
+  `blue-shirt`), or from the file name for one-entity files. Ids are derived from handles. Both
+  are stable across runs and machines, so URLs and ids can be hard-coded in tests. Set `id`
+  explicitly only to reproduce a specific Shopify id.
+- **Money** is an integer number of cents (`1999`) or a decimal string (`"19.99"`). A JSON
+  float (`19.99`) is rejected, because it is ambiguous. Liquid sees cents, as on Shopify.
+- **Dates** are ISO 8601 strings: a day, `"2024-05-01"`, or a day and a time,
+  `"2024-05-01T10:00:00Z"` (or a space for the `T`), with `Z`, an offset (`+02:00`) or neither,
+  for the shop's `timezone`. `now` is a date too. Any other form (`"May 1, 2024"`,
+  `"2024/05/01"`, `"2024-5-1"`, an RFC 2822 date, a time alone) is an `invalid_date` error,
+  though the `date` filter of a theme still reads it. Entities without dates get fixed ones, so
+  renders are reproducible.
+- **References** between entities use handles (products, collections, pages, blogs), emails
+  (customers) and SKUs or ids (variants). A reference to something that does not exist is an
+  error, with a suggestion when a close match exists.
+- **HTML** fields (`description`, `content`, `body`) are inserted as written.
+
+## Products
+
+The smallest product:
+
+```json
+{ "title": "Blue shirt", "price": "19.99" }
+```
+
+It gets a single default variant, like a product without options in the Shopify admin. A
+product with options lists its variants; each gives one value per option:
+
+```json
+{
+  "title": "Organic Cotton T-Shirt",
+  "vendor": "Local Supply Co.",
+  "type": "Shirts",
+  "tags": ["cotton", "new"],
+  "options": ["Color", "Size"],
+  "price": "28.00",
+  "compare_at_price": "35.00",
+  "images": [
+    { "src": "products/tee-white.jpg", "alt": "White t-shirt", "width": 1600, "height": 2000 },
+    "products/tee-black.jpg"
+  ],
+  "variants": [
+    { "options": ["White", "S"], "sku": "TEE-WHT-S", "inventory_quantity": 12, "image": "products/tee-white.jpg" },
+    { "options": ["White", "M"], "sku": "TEE-WHT-M", "inventory_quantity": 0 },
+    { "options": ["Black", "S"], "sku": "TEE-BLK-S", "price": "30.00", "available": false }
+  ],
+  "collections": ["apparel"],
+  "metafields": { "custom": { "care": "Machine wash cold" } }
+}
+```
+
+- `price` and `compare_at_price` on the product apply to the variants that do not set their own.
+- **Availability** follows Shopify's rules. A variant with `inventory_quantity` is tracked: it
+  is available while the quantity is above zero, or always with
+  `"inventory_policy": "continue"`. A variant without `inventory_quantity` is not tracked and
+  always available. `available` forces the answer either way. `"available": false` alone also
+  makes the variant tracked with a quantity of 0, as a sold-out variant is on Shopify, so themes
+  show "Sold out". Adding more than the stock to the cart fails as it does on Shopify.
+  `"available": false` with an `inventory_quantity` above 0 is a warning
+  (`unavailable_in_stock`): Shopify never has both. lsf keeps the variant unavailable with its
+  stock, which Horizon shows as "Unavailable".
+- `options` can spell out the order of the values:
+  `{ "name": "Size", "values": ["S", "M", "L"] }`. A value can carry a [swatch](#swatches).
+- `selling_plan_groups` and `requires_selling_plan` sell the product by subscription: see
+  [selling plans](#selling-plans).
+- A variant's `store_availabilities` says where it can be picked up: see
+  [store pickup](#store-pickup).
+- Use `media` instead of `images` to mix images with videos, external videos and 3D models.
+- `recommendations` lists the handles returned by product recommendations; by default they are
+  other products of the same collections.
+- `template_suffix` selects an alternate template (`templates/product.<suffix>.json`).
+- `status` (`active`, `draft`, `archived`) and `published` (on the Online Store, `true` by
+  default) say whether the product is on the storefront: only an active, published product is.
+  The others have no page, are in no collection, cannot be bought, and what names them (a
+  collection, a menu, an order) leaves them out without an error; the Admin API lists them with
+  their status.
+
+## Collections
+
+```json
+{
+  "collections": [
+    { "title": "Apparel", "products": ["organic-cotton-t-shirt", "linen-overshirt"] },
+    { "title": "Sale", "rules": [{ "column": "tag", "condition": "sale" }] },
+    {
+      "title": "Under $30",
+      "sort_order": "price-ascending",
+      "rules": [{ "column": "price", "relation": "less_than", "condition": "3000" }]
+    }
+  ]
+}
+```
+
+A product belongs to a collection when the collection lists it in `products`, when the product
+lists the collection in its own `collections`, or when it matches the collection's `rules`
+(all of them, or any of them with `"disjunctive": true`).
+
+`collections.all` always exists and contains every product, sorted by title as on Shopify.
+Define a collection with the handle `all` only to change its title or order.
+
+Storefront filtering (`collection.filters`, `?filter.v.availability=1`,
+`?filter.v.price.gte=10`, `?filter.p.vendor=...`, `?filter.v.option.color=...`), sorting
+(`?sort_by=`) and tag URLs (`/collections/<handle>/<tag>`) work from this data without any
+extra configuration.
+
+## Selling plans
+
+A selling plan is a way of buying a product other than once: a subscription, a pre-order.
+Plans come in groups, which is what a subscription app creates.
+
+```json
+{
+  "selling_plan_groups": [
+    {
+      "name": "Subscribe and save",
+      "options": ["Delivery frequency"],
+      "selling_plans": [
+        {
+          "name": "Deliver every month, 10% off",
+          "options": ["Every month"],
+          "price_adjustments": [{ "value_type": "percentage", "value": 10 }]
+        },
+        {
+          "name": "Deliver every 3 months",
+          "options": ["Every 3 months"]
+        }
+      ],
+      "products": ["organic-cotton-t-shirt"]
+    }
+  ]
+}
+```
+
+- A product is sold with a group when the group lists it in `products`, or when the product
+  names the group: `"selling_plan_groups": ["Subscribe and save"]`. The plans apply to every
+  variant of the product.
+- `"requires_selling_plan": true` on a product means it cannot be bought once.
+- A **price adjustment** has a `value_type`: `percentage` (`value` percent off), `fixed_amount`
+  (`value` off, an amount of money) or `price` (`value` is the price). A plan has at most two:
+  the first one gives the price, the second one is what later orders cost. Without any, the
+  plan costs what the variant costs.
+- `options` of the group are the names of what the plans differ by, and each plan gives one
+  value per option. They default to one option, `Delivery frequency`, whose value is the
+  plan's name.
+- `checkout_charge` is what is paid at checkout, for a deposit:
+  `{ "value_type": "percentage", "value": 50 }`. It defaults to the whole price. The checkout
+  of an [app](checkout.md#deferred-payments) charges only that today, and shows the rest as due
+  later.
+- `recurring_deliveries` defaults to `true`. Ids are generated and stable; set `id` on a plan
+  to reproduce a Shopify id.
+
+In Liquid, `product.selling_plan_groups`, `variant.selling_plan_allocations` and
+`product.selected_or_first_available_selling_plan_allocation` are filled. `?selling_plan=<id>`
+selects a plan (`product.selected_selling_plan`, `selling_plan.selected`), and with `?variant=`
+an allocation (`product.selected_selling_plan_allocation`). `/products/<handle>.js` and the
+`json` filter list the groups and the allocations as Shopify does.
+
+In the cart, `selling_plan` is accepted by `/cart/add.js` and `/cart/change.js`. The line then
+has the plan's price and its `selling_plan_allocation`, and stays separate from the same
+variant bought once. A product is refused with a plan it is not sold with, and without one
+when it requires one.
+
+## Store pickup
+
+`locations` are the places the store stocks its products at.
+
+```json
+{
+  "locations": [
+    {
+      "name": "Portland flagship",
+      "address": {
+        "address1": "12 Maple Street",
+        "city": "Portland",
+        "province_code": "OR",
+        "zip": "97204",
+        "country_code": "US",
+        "phone": "+1 503 555 0100"
+      },
+      "pick_up_time": "Usually ready in 2 hours",
+      "latitude": 45.5202,
+      "longitude": -122.6742
+    },
+    { "name": "Seattle warehouse", "pick_up_enabled": false }
+  ]
+}
+```
+
+- `pick_up_enabled` and `physical_storefront` default to `true`, `pick_up_time` to
+  `Usually ready in 24 hours`.
+- Every location stocks every variant, and a variant is in stock there when it is available. A
+  variant that lists `store_availabilities` is stocked by those locations only, each with its
+  own stock:
+  `"store_availabilities": { "Portland flagship": true, "Seattle warehouse": false }`.
+
+In Liquid, `variant.store_availabilities` lists a `store_availability` per location, with its
+`location` (`name`, `address`, `latitude`, `longitude`, `metafields`). As on Shopify, only the
+selected variant and the first available one have them: the other variants of a product have
+an empty list.
+
+`/variants/<id>?section_id=<section>` renders a section for a variant, which the section reads
+as `product_variant`. Themes fetch that URL to show pickup availability. Without `section_id`,
+the URL leads to the product with the variant selected.
+
+## Swatches
+
+A swatch shows an option value as a color or an image instead of its name. `swatches` gives
+them by the name of the value, for the whole store:
+
+```json
+{
+  "swatches": {
+    "White": "#f4f1ea",
+    "Sage": "rgb(156, 175, 136)",
+    "Floral": { "image": "swatches/floral.jpg" },
+    "Sand": { "color": "#d8c7a8", "image": "swatches/sand.jpg" }
+  }
+}
+```
+
+Every option value with one of these names gets the swatch, whatever the product and the
+option. A product can give its own to a value, in the long form of `options`:
+
+```json
+{
+  "options": [
+    { "name": "Color", "values": ["White", { "name": "Sunset", "swatch": "#ff7a00" }] },
+    "Size"
+  ]
+}
+```
+
+In Liquid, `product_option_value.swatch` has a `color` and an `image`, and is `nil` for a
+value without a swatch. In collection filters, a filter whose values have swatches has the
+`swatch` presentation, and each `filter_value.swatch` is filled.
+
+## Pages, blogs and articles
+
+```json
+{
+  "pages": [
+    { "title": "About", "content": "<p>Since 2012.</p>" },
+    { "title": "Contact", "template_suffix": "contact" }
+  ],
+  "blogs": [
+    {
+      "title": "Journal",
+      "comments_enabled": true,
+      "articles": [
+        {
+          "title": "How to care for linen",
+          "author": "Sam",
+          "tags": ["care"],
+          "published_at": "2024-05-01",
+          "image": { "src": "blog/linen.jpg", "width": 1600, "height": 900 },
+          "excerpt": "<p>Linen gets better with every wash.</p>",
+          "content": "<p>Wash cold, hang dry.</p>",
+          "comments": [{ "author": "Alex", "content": "Great tips." }]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Menus
+
+`menus` maps a menu handle (`main-menu`, `footer`, ...) to its links. A link points at a
+resource with one of `url`, `collection`, `product`, `page`, `blog`, `article`
+(`"<blog>/<article>"`) or `policy`; its URL, `link.type` and `link.object` follow from it.
+`link.active` and `link.child_active` follow from the page being rendered.
+
+```json
+{
+  "menus": {
+    "main-menu": {
+      "links": [
+        { "title": "Home", "url": "/" },
+        {
+          "title": "Shop",
+          "collection": "all",
+          "links": [{ "title": "Apparel", "collection": "apparel" }]
+        },
+        { "title": "About", "page": "about" }
+      ]
+    }
+  }
+}
+```
+
+## The shop
+
+Every field of `shop` is optional.
+
+```json
+{
+  "shop": {
+    "name": "Local Supply Co.",
+    "currency": "EUR",
+    "money_format": "{{amount_with_comma_separator}} €",
+    "timezone": "Europe/Paris",
+    "policies": { "refund_policy": { "body": "<p>30 days.</p>" } },
+    "enabled_payment_types": ["visa", "master", "paypal"]
+  }
+}
+```
+
+- `money_format` and `money_with_currency_format` default to the usual format of the currency.
+- `timezone` is the zone dates are displayed in by the `date` filter.
+- `password` is the password the `/password` page accepts. It is `password` when you do not
+  set it. The storefront is never locked: the page is always there, and nothing leads to it.
+- Each policy that is set gets a page under `/policies/`.
+
+## Customers and sessions
+
+A **customer** exists in the store. A **session** is one browser's state: who is logged in,
+what is in the cart, which country is selected.
+
+```json
+{
+  "customers": [
+    {
+      "email": "jane.doe@example.com",
+      "first_name": "Jane",
+      "last_name": "Doe",
+      "tags": ["vip"],
+      "addresses": [{ "address1": "12 Maple Street", "city": "Portland", "country_code": "US" }],
+      "orders": [{ "line_items": [{ "variant": "TEE-WHT-S", "quantity": 2 }] }]
+    }
+  ],
+  "session": {
+    "customer": "jane.doe@example.com",
+    "cart": { "items": [{ "variant": "TEE-WHT-S", "quantity": 1 }], "note": "Gift wrap" },
+    "country": "FR"
+  }
+}
+```
+
+`session` is what every new browser session starts with. Leave it out for an anonymous visitor
+with an empty cart. A variant is referenced by its SKU, by its id, or by a product handle
+(meaning the product's first variant).
+
+A cart item bought with a [selling plan](#selling-plans) names the plan, or gives its id:
+`{ "variant": "TEE-WHT-S", "selling_plan": "Deliver every month, 10% off" }`.
+
+`session.customer` is the email of a customer, `"default"` for the first customer of the data,
+or `"none"`. When the data has no customer at all, there is still one to log in as:
+`customer@example.com`.
+
+### Logging in
+
+Customer accounts are Shopify's new customer accounts: they are hosted by Shopify and are not
+part of a theme. Here, `/account` is a page of local-storefront that stands in for them. It
+lists the customers of the data: click one to be logged in as them, or "Nobody" to be logged
+out. Every account link of a theme (`routes.account_login_url`, `routes.storefront_login_url`,
+...) leads to that page, and so do its login and register forms.
+
+Classic customer accounts are not simulated: the theme's `templates/customers` are never
+rendered (`serve` and `check` say so), and customers have no password. Data that still has
+`shop.customer_accounts` or a customer's `password` is read as before: those fields are ignored,
+with a warning to remove them.
+
+`npx local-storefront serve --customer <email>` starts every visitor logged in as that customer.
+It also accepts `default` and `none`.
+
+At the [checkout of an app](checkout.md#log-in-as-a-customer), the customers are the login
+profiles: "Log in" in the Contact section lists them, and picking one logs the checkout (and the
+session) in as them, with their saved addresses (the first one is the default) and, for a B2B
+customer, the locations they buy for. Give the data a customer of each kind you test: a new one
+(no orders, no addresses), a returning one (`addresses`, `orders`, `tags`, `metafields`), a B2B
+buyer with several `company_locations`, a customer in another country. The demo store has one of
+each.
+
+### B2B customers
+
+A B2B customer buys for a **company**, at one of its **locations**. Describe the company, then
+name it in the customer:
+
+```json
+{
+  "companies": [
+    {
+      "name": "Northwind Hotels",
+      "external_id": "NW-001",
+      "metafields": { "custom": { "payment_terms": "Net 30" } },
+      "locations": [
+        {
+          "name": "Northwind Portland",
+          "tax_registration_id": "93-1234567",
+          "shipping_address": { "address1": "815 Harbor Way", "city": "Portland", "country_code": "US" },
+          "metafields": { "custom": { "delivery_notes": "Loading dock B" } }
+        },
+        { "name": "Northwind Seattle" }
+      ]
+    }
+  ],
+  "customers": [
+    {
+      "email": "alex.morgan@example.com",
+      "first_name": "Alex",
+      "company": "Northwind Hotels",
+      "metafields": { "custom": { "job_title": "Purchasing manager" } }
+    }
+  ]
+}
+```
+
+- The customer can buy for every location of the company. List some in `company_locations` to
+  restrict them: `"company_locations": ["Northwind Seattle"]`.
+- They start at the first location. `session.company_location` names another one.
+- In Liquid, `customer.b2b?` is true, and `customer.current_company`,
+  `customer.current_location` and `customer.company_available_locations` are filled.
+- `location.url_to_set_as_current` changes the location, as on Shopify.
+- The [local checkout](checkout.md) shows what Shopify's Functions read of a B2B buyer
+  (`purchasingCompany`), and you can set it. A company has `created_at` and `updated_at`, a
+  location the same plus `locale` (`"fr"`), `orders_count` and `total_spent` (`"1250.00"`). The
+  customer is the contact of their company: `company_contact` holds their `title`, `locale`,
+  `created_at` and `updated_at`.
+
+```json
+{
+  "companies": [
+    {
+      "name": "Northwind Hotels",
+      "created_at": "2023-06-01",
+      "locations": [
+        { "name": "Northwind Portland", "locale": "en", "orders_count": 12, "total_spent": "8450.00" }
+      ]
+    }
+  ],
+  "customers": [
+    {
+      "email": "alex.morgan@example.com",
+      "company": "Northwind Hotels",
+      "company_contact": { "title": "Purchasing manager", "locale": "en" }
+    }
+  ]
+}
+```
+
+  What is not set has a value: the dates are 2024-01-01 12:00 UTC plus one day per company,
+  the dates of a location and of a contact are those of their company (`updated_at` those of
+  `created_at`), the language is empty, and a location has no order and has spent nothing. The
+  orders of the customers are not counted in `orders_count`: it is what you write.
+
+Catalogs are not simulated: a B2B customer sees the same products and prices as everyone.
+
+Tests usually set the session per test rather than in the files, by sending it to the running
+server. The body is a session, optionally with a `data` object: a data file applied on top of
+the files on disk for that session only.
+
+```bash
+curl -X PUT http://127.0.0.1:9292/__lsf/session \
+  -H 'x-lsf-session: my-test' -H 'content-type: application/json' \
+  -d '{"customer": "jane.doe@example.com", "data": {"shop": {"name": "Another name"}}}'
+```
+
+A person can do the same from a browser: `/__lsf` lists the customers, and
+`/__lsf/login?customer=<email>` logs the browser in as one of them (`default` and `none` work
+too).
+
+A wrong body is answered with `422` and the same diagnostics as
+`npx local-storefront validate --format json`.
+
+## Gift cards
+
+Each gift card has a page rendered by `templates/gift_card.liquid`. Its URL is listed by
+`npx local-storefront routes`.
+
+```json
+{
+  "gift_cards": [
+    { "code": "WCGX7X97G74JGDGC", "initial_value": "50.00", "balance": "32.50", "expires_on": "2030-12-31" }
+  ]
+}
+```
+
+## Checkout
+
+The `checkout` section sets up the local checkout of a Shopify app (`npx local-storefront
+app dev --app <dir>`, see [checkout](checkout.md)). Every field has a default, and the section
+changes nothing for a theme.
+
+```json
+{
+  "checkout": {
+    "shipping_rates": [{ "handle": "standard", "title": "Standard", "price": "4.90" }],
+    "payment_methods": [{ "handle": "card", "name": "Credit card" }],
+    "discounts": [
+      {
+        "function": "volume-discount",
+        "title": "Volume",
+        "classes": ["PRODUCT"],
+        "metafields": { "$app.function-configuration": { "type": "json", "value": { "percentage": 10 } } }
+      }
+    ],
+    "functions": { "delivery-rules": { "enabled": true, "metafields": { "$app.function-configuration": { "type": "json", "value": {} } } } },
+    "tax_rate": 20
+  }
+}
+```
+
+- `shipping_rates`: the delivery options offered to every address. Without it, one: "Standard"
+  at 5.00.
+- `payment_methods`: without it, "Credit card", "Cash on Delivery" and "Bank Deposit".
+  `placements` says where a method is offered, which payment customization Functions read:
+  `["PAYMENT_METHOD"]` (the list of the checkout, the default) and/or `["ACCELERATED_CHECKOUT"]`
+  (the express buttons). The page shows the methods of `PAYMENT_METHOD` in its list, and those of
+  `ACCELERATED_CHECKOUT` as express buttons above the contact section, once the payment
+  customizations ran (one can hide a method in one placement and leave it in the other). PayPal
+  with PayPal Express on is in both.
+- `discounts`: each one uses a discount Function of the app by its handle. A `code` makes it a
+  code discount; without one it is automatic. `classes` (`PRODUCT`, `ORDER`, `SHIPPING`) says
+  what it may reduce, all three by default. `metafields` are those of the discount, by
+  `"namespace.key"`, in the same shorthand as other metafields. `id` is the number of the id
+  its Function reads (`gid://shopify/DiscountAutomaticNode/<id>`), its position in the list from
+  1 by default.
+- `functions`: the other Functions (cart transform, delivery or payment customization,
+  validation), by the handle of the Function: `metafields`, their settings, and `enabled`, whether
+  the shop has an owner of it (the payment customization, … the app creates) and it is on. As on
+  Shopify, the shop's checkout runs such a Function only through an enabled owner: `true` runs
+  it, `false` is an owner turned off, and without `enabled` the shop has none (as after an
+  install, until the app creates one through the Admin API). A scenario that names the Function
+  in `extensions` runs it anyway, with these metafields
+  ([what runs](checkout.md#owners-and-scenarios)).
+- `tax_rate`: a percentage, added to the discounted subtotal.
+
+### Checkout scenarios
+
+A scenario is a named setup of the local checkout: one file in `checkouts/`, named after the
+scenario (`checkouts/b2b-seattle.json` is `b2b-seattle`). The home page of the checkout lists
+them and opens a fresh checkout for each; `app function run --scenario <name>` runs the Functions
+for one ([checkout](checkout.md#scenarios)). A scenario is a set of overrides on top of the
+store data: what it does not set stays as the data says.
+
+```json
+{
+  "$schema": "../schema/checkout-scenario.schema.json",
+  "title": "B2B buyer at the Seattle location",
+  "description": "Four tees, a company customer, and a shipping rate for pallets.",
+  "session": {
+    "customer": "alex.morgan@example.com",
+    "company_location": "Northwind Seattle",
+    "country": "US",
+    "cart": {
+      "items": [{ "variant": "TEE-BLK-M", "quantity": 4 }],
+      "note": "Deliver to dock B",
+      "attributes": { "po_number": "PO-1042" }
+    }
+  },
+  "entered": {
+    "email": "alex.morgan@example.com",
+    "shipping_address": { "last_name": "Morgan", "address1": "2200 Alder Street", "city": "Seattle", "country_code": "US" },
+    "discount_codes": ["SAVE10"],
+    "delivery": "pallet",
+    "payment": "bank"
+  },
+  "language": "en",
+  "checkout": {
+    "shipping_rates": [{ "handle": "pallet", "title": "Pallet", "price": "45.00" }],
+    "discounts": [{ "function": "volume-discount", "code": "SAVE10", "classes": ["ORDER"] }]
+  },
+  "variant": "standard",
+  "extensions": ["volume-discount", "gift-message"]
+}
+```
+
+Every field is optional.
+
+- `title` and `description` are for the home page. The title defaults to the file name.
+- `session` is a [session](#customers-and-sessions), applied on top of the `session` of the
+  store data: `customer`, `cart` (`items` with `variant`, `quantity`, `properties` and
+  `selling_plan`, `note`, `attributes`), `country` and `company_location`.
+- `entered` is what the buyer already typed and chose: `email`, `phone`, `shipping_address`
+  (`first_name`, `last_name`, `company`, `address1`, `address2`, `city`, `country_code`,
+  `province_code`, `zip`, `phone`), `delivery` (the handle of a shipping rate), `payment` (the
+  handle of a payment method) and `discount_codes`. A code that no discount has is entered all
+  the same, and refused.
+- `language` is a language of the store (`localization.languages`). The checkout opens under
+  its locale root (`/fr/checkouts/cn/...`).
+- `checkout` overrides the [`checkout` section](#checkout) of the store data. Every field that is
+  present replaces the store's: `shipping_rates`, `payment_methods`, `discounts` (`[]` runs no
+  discount), `tax_rate`. `functions` replaces the settings of the Functions it names and keeps
+  those of the others; an entry without `enabled` keeps the store's owner of it.
+- `variant` is the look: `standard` or `shop`. `?variant=` in the URL still wins.
+- `extensions` lists the handles of the extensions (Functions and checkout UI extensions) that
+  run. The others of the app are left out. It narrows what `--extension` allows. The Functions it
+  names run whether or not the shop has an owner of them: a scenario that names none shows the
+  shop's checkout, where only those with an enabled owner run. A Function you add to the app
+  later is not in the `extensions` of the scenarios written before it: add its handle.
+- `expect` is what the checkout must look like once the Functions ran, which `app check`
+  checks: the payment methods, express buttons, delivery options, discounts, lines and errors,
+  each with `includes`, `excludes` and `equals`, and exact `totals`
+  (`"expect": { "express_methods": { "excludes": ["paypal"] }, "totals": { "total": "96.00" } }`).
+  See [expected results](checkout.md#expected-results).
+
+A scenario that does not validate is still listed, with its errors, and cannot be opened.
+`validate` reports it with the file `checkouts/<name>.json` and a pointer into it
+(`/session/cart/items/0/variant`). Files that are not `.json`, and folders, are ignored.
+Scenarios are reloaded when the files change, like the rest of the data. The built-in demo
+store has none: `npx local-storefront app init` writes a set.
+
+## Localization
+
+```json
+{
+  "localization": {
+    "countries": [{ "iso_code": "US", "popular": true }, { "iso_code": "FR" }],
+    "languages": [{ "iso_code": "en" }, { "iso_code": "fr" }]
+  }
+}
+```
+
+The first language is the primary one, served at `/`. The others are served under
+`/<iso_code>/` (`/fr/products/blue-shirt`) and use the theme's `locales/<iso_code>.json`.
+Names and currencies of countries default to built-in values. Without `countries`, the store
+sells in one country: the shop's (`shop.address.country_code`), or `US`. The localization form
+(`{% form 'localization' %}`) switches the session's country and language. A visitor who
+selected no country is in the shop's (`shop.address.country_code`), the one of its primary
+market, on the storefront as at the checkout; in the first country when the store does not sell
+to the shop's.
+
+`markets` groups countries the way Shopify's markets do. The checkout Functions read the
+market of the buyer (`localization.market`) and of an address (`MailingAddress.market`):
+
+```json
+{
+  "localization": {
+    "countries": [{ "iso_code": "FR" }, { "iso_code": "DE" }, { "iso_code": "US" }],
+    "markets": [
+      { "handle": "europe", "countries": ["FR", "DE"], "metafields": { "custom": { "tier": "gold" } } }
+    ]
+  }
+}
+```
+
+A country in no market is a market of its own, named after the country (`france`, `united-states`).
+An address in a country the store does not sell to has no market.
+
+## Images and files
+
+An image is a path inside `files/`, optionally with metadata:
+
+```json
+"products/tee-white.jpg"
+{ "src": "products/tee-white.jpg", "alt": "White t-shirt", "width": 1600, "height": 2000 }
+```
+
+URLs keep the shape Shopify gives them but point to the local server, never to Shopify's CDN:
+
+```text
+{{ product.featured_image | image_url: width: 400, height: 400, crop: 'center' }}
+→ //localhost:9292/cdn/shop/files/products/tee-white.jpg?crop=center&height=400&v=1651229318&width=400
+```
+
+The server resizes and crops on the fly with Shopify's parameters: `width`, `height`, `crop`
+(`top`, `center`, `bottom`, `left`, `right`, or a region with `crop_left`, `crop_top`,
+`crop_width`, `crop_height`), `pad_color`, `format` and `quality`. Images are never scaled up
+beyond their own size, as on Shopify. The legacy `img_url` sizes
+(`shirt_400x400_crop_center.jpg`) work too.
+
+**The file does not have to exist.** When it is missing, the server draws a placeholder of the
+declared `width` × `height` (1200 × 1200 when not declared) showing the file name, and answers
+with the header `x-lsf-placeholder: 1`. Layout, aspect ratios and `srcset` are then the same as
+with real images, so fixtures do not need to ship binaries. When the file exists, its real
+size is read from it.
+
+`files` gives metadata to files that are referenced by name from theme settings or metafields:
+
+```json
+{ "files": { "hero.jpg": { "alt": "Storefront", "width": 2400, "height": 1200 } } }
+```
+
+A setting of type `image_picker` holding `shopify://shop_images/hero.jpg` resolves to
+`files/hero.jpg`.
+
+Fonts picked with `font_picker` come from Shopify's font library, which is not available
+offline. Put a font at `files/fonts/<file name>` to serve the real file; otherwise a blank font
+is served so that browsers fall back to the theme's fallback stack without network errors.
+
+## Metafields and metaobjects
+
+Metafields are grouped by namespace, then key. A plain value gets its type inferred; spell out
+`{ "type", "value" }` for anything else. References are written as handles, files as paths
+inside `files/`.
+
+```json
+{
+  "metafields": {
+    "custom": {
+      "care": "Machine wash cold",
+      "rating": 5,
+      "organic": true,
+      "size_guide": { "type": "page_reference", "value": "size-guide" },
+      "related": { "type": "list.product_reference", "value": ["linen-overshirt"] },
+      "swatch": { "type": "color", "value": "#f4f1ea" },
+      "lookbook": { "type": "file_reference", "value": "lookbook.jpg" }
+    }
+  }
+}
+```
+
+`{{ product.metafields.custom.care }}` and
+`{{ product.metafields.custom.size_guide.value.title }}` then behave as on Shopify, including
+`metafield_tag` and `metafield_text`.
+
+A typed value is checked against its type, as Shopify checks it. `{"type": "number_integer",
+"value": "two"}` is an `invalid_metafield` error, and so is a `weight` in `"kgs"` or a
+`rating` outside its scale. A `weight`, `dimension` or `volume` takes the units Shopify lists
+(`kilograms`, `centimeters`, `milliliters`...) and their short forms (`kg`, `cm`, `ml`). A
+`language` is a locale code (`fr`, `pt-BR`). A type Shopify does not have is an
+`unknown_metafield_type`. A
+reference that names nothing of the data is an `unknown_reference`, with the closest name:
+products, variants (by SKU or id), collections, pages, articles (`blog/article`) and
+metaobjects (`type/handle`). A `file_reference` to a file that is not in `files/` is no error:
+it shows as a placeholder.
+
+A `file_reference` is an image when its extension is one (`.jpg`, `.png`, `.webp`...) and a
+video for `.mp4`, `.mov`, `.webm` and `.m4v`: `sources`, `preview_image`, `video_tag` and
+`metafield_tag` work.
+A video's poster is the `.jpg` of the same name (`looks/summer.jpg` for `looks/summer.mp4`),
+and its size the one declared in `files` (1920×1080 otherwise). Any other file has a `url`.
+
+Metaobjects are listed by type:
+
+```json
+{
+  "metaobjects": {
+    "designer": [{ "handle": "sam", "fields": { "name": "Sam", "portrait": { "type": "file_reference", "value": "sam.jpg" } } }]
+  }
+}
+```
+
+and read with `{{ metaobjects.designer.sam.name }}` or
+`{% for d in metaobjects.designer.values %}`.
+
+A type whose theme has `templates/metaobject/<type>.json` (or `.liquid`) is a type with web
+pages on Shopify: each entry is served at `/pages/<type>/<handle>`, the template sees it as
+`metaobject`, and `metaobject.system.url` is that URL. Without the template the entry has no
+page and `system.url` is blank. `"template_suffix": "alt"` on an entry renders it with
+`templates/metaobject/<type>.alt.json`, and `?view=alt` does the same for one request. The page
+title is the entry's `title` or `name` field, or its handle. `shopify://metaobjects/<type>/<handle>`
+in a `url` setting leads to the page.
+
+The Functions of the [local checkout](checkout.md) read the same metaobjects as
+`shop.metaobject(handle: {type: "designer", handle: "sam"})`, with their `field(key:)`.
+
+The types an app owns are written `$app:<type>` (`"$app:author"`), as its reserved metafield
+namespaces are (`$app:config`). Shopify writes them in full, `app--<app id>--author`, which a
+theme's Liquid uses: `metaobjects['app--1234--author']` and `metaobjects['$app:author']` both
+find them, whatever the id, since the store data does not know it.
+
+
+## Time and theme settings
+
+- `now` freezes the clock: `"now": "2025-01-15T10:00:00Z"`. `{{ 'now' | date: ... }}`, sale
+  countdowns and "new" badges then render the same on every run. As on Shopify, where each
+  `'now'` is a new reading of the clock, each `'now'` of a render is one nanosecond after the
+  previous one: `{{ 'now' | date: '%N' }}` gives `000000000`, then `000000001`, and so on, so
+  ids built from it differ. Without `now`, `'now'` reads the real clock each time.
+- `theme_settings` overrides values of `config/settings_data.json` by setting id, without
+  touching the theme: `"theme_settings": { "cart_type": "drawer" }`. Each id and value is
+  checked against the theme's `config/settings_schema.json`: an id the theme does not have is
+  an `unknown_setting`, and a value its setting does not take (an option a `select` does not
+  have, a `range` out of bounds, a `checkbox` that is not `true` or `false`) an
+  `invalid_setting`. Without a theme, `validate` cannot check them, and a warning says so.
+
+## The app
+
+With `serve --app`, `app` is the app as the store has it installed, for its theme app
+extensions:
+
+```json
+{
+  "app": {
+    "metafields": { "reviews": { "badge_enabled": true } },
+    "embeds": { "chat-bubble": true, "reviews-loader": { "settings": { "api_key": "test-key" } } }
+  }
+}
+```
+
+- `metafields` are its app-data metafields, by namespace then key, written as other
+  metafields. The Liquid of its blocks reads them as `app.metafields.reviews.badge_enabled`,
+  and the `available_if` of a block tests them.
+- `embeds` turns its app embed blocks on or off, by the name of their file in `blocks/`: `true`,
+  `false`, or `{"settings": {...}}` to turn one on with these settings. What it does not name
+  stays as `config/settings_data.json` has it.
+
+## Error codes
+
+| Code | Meaning |
+|---|---|
+| `invalid_json` | The file is not valid JSON. The hint gives the line and column. |
+| `unreadable_file` | The file could not be read. |
+| `unknown_field` | A field that does not exist. The hint suggests the closest one. The field is left out, the rest of the file is read. |
+| `classic_customer_accounts` | A warning: `shop.customer_accounts` or a customer's `password`, which classic customer accounts had. The field is ignored. |
+| `missing_field` | A required field is absent. |
+| `wrong_type` | A value of the wrong JSON type. |
+| `invalid_value`, `invalid_format` | A value outside what the field accepts, or not in its format. Money as a JSON float (`19.99`) is an `invalid_value`, and a string that is not an amount (`"19.999"`) an `invalid_format`; the hint says what the field takes. |
+| `invalid_money`, `invalid_date`, `invalid_email`, `invalid_handle`, `invalid_timezone`, `invalid_gift_card_code` | A value that does not parse as what it should be. `invalid_money` is a shipping rate below zero. |
+| `duplicate_handle`, `duplicate_id`, `duplicate_email`, `duplicate_menu`, `duplicate_variant`, `duplicate_gift_card` | Two entities with the same identity. |
+| `duplicate_section` | `shop`, `localization`, `session`, `checkout` or `now` defined in two files. |
+| `unknown_language` | A checkout scenario names a language that is not in `localization.languages`. |
+| `unknown_product`, `unknown_collection`, `unknown_variant`, `unknown_customer`, `unknown_company`, `unknown_location`, `unknown_country`, `unknown_image`, `unknown_reference` | A reference to something that is not in the data, in a file of `checkouts/` as anywhere else. The hint suggests the closest match. A link of a menu is an `unknown_reference`, whatever it names (a product, a collection, a page, an article, a policy), and so is a reference of a metafield, and a shipping rate or a payment method a scenario's `entered` names. |
+| `duplicate_company`, `duplicate_location`, `missing_locations`, `missing_company` | A company without a location, two companies or two locations with the same name, or a customer that lists locations or a `company_contact` without a company. |
+| `duplicate_market_country` | A country in two `localization.markets`. |
+| `unknown_return_line` | A return of an order names a variant that is not a line of the order. |
+| `expect_checks_nothing` (warning) | An `excludes` of a scenario's `expect` names a payment method, express button or delivery option the checkout does not offer, so it checks nothing. The hint lists what it offers. |
+| `invalid_throttle` | The `throttle` of a session sent to `PUT /__lsf/session` is not one `--throttle` takes. |
+| `unknown_selling_plan`, `missing_selling_plan`, `duplicate_selling_plan` | A selling plan or a group that is not in the data, or that the product is not sold with; a group without a plan, or a product that requires a plan and has none; two groups or two plans with the same name. |
+| `invalid_metafield`, `unknown_metafield_type` | A typed metafield (or field of a metaobject) whose value its type refuses, or whose type Shopify does not have. The hint shows how the type is written. |
+| `unknown_setting`, `invalid_setting` | A `theme_settings` id that `config/settings_schema.json` does not have, or a value its setting does not take. The hint suggests the closest id or option. |
+| `unchecked_theme_settings` (warning) | The data has `theme_settings` and there is no theme to check them against. |
+| `invalid_color`, `empty_swatch` | A swatch whose color is not a CSS color, or that has neither a color nor an image. |
+| `missing_price` | A product without a price on itself or on its variants. |
+| `missing_variants`, `missing_options`, `option_mismatch`, `too_many_options` | The options of a product and the option values of its variants do not line up. |
+| `media_conflict`, `missing_sources`, `missing_external_video` | Incomplete or contradictory product media. |
+| `ambiguous_link` | A menu link that points at more than one thing. |
+| `missing_locale_file` (warning) | A language the theme has no `locales/<code>.json` for. |
+| `gift_card_balance` (warning) | A gift card whose balance is above its initial value. |
+| `unavailable_in_stock` (warning) | A variant with `"available": false` and an `inventory_quantity` above 0, which Shopify never has. It stays unavailable, with its stock. The hint says which field to remove. |
+
+`path` is always a JSON pointer into `file`, so the value to fix can be located mechanically.
+
+An entity with a value that cannot be read (a `wrong_type`, an `invalid_value`, an
+`invalid_format`, a `missing_field`) is left out. The rest of its file is still read, with its
+references, so one run reports every problem. Each reference to the entity left out is an error
+too (`unknown_product`, `unknown_variant`, `unknown_customer`, `unknown_reference`), and its
+hint says so: `the product "a" is left out because products/a.json has errors`. Fix that file,
+and these errors go away with it.
+
+## Field reference
+
+Every field of every type is listed in [data-reference.md](data-reference.md), which is
+generated from the JSON Schema the validator uses.