The Product

The Product is the one thing a Product Model describes: what it promises, and where its boundary lies. Every model has exactly one, in product.md. The rest of the model (who uses it, where, what it can do and under which rules) explains that promise.

In practice

The fixture shop's Product:

product/product.md

---
id: fixture-shop
summary: Browse a product catalog, buy products, and manage the resulting orders.
category: commerce
tags: [commerce, fixture]
authors:
  - name: pdd-kit
license: MIT
languages: [en, de]
limitations: []
---

# Fixture Shop

A tiny webshop where shoppers browse a catalog and buy products, and store admins manage the resulting orders.

## Intent

Exercise the complete pdd-kit report contract with a small deterministic product.

One Product or several?

A website, a mobile app, a CLI and a public API are usually Interfaces of one Product, not separate Products. Keep separate Products for genuinely separate promises.

Repository layout doesn't decide it: several packages may build one Product. Today a repository holds one Product Model in one product-model/; support for several Products in one repository is planned (#46).

The file

product.md, or product/product.md once it has a logo. The H1 is the Product's name and the paragraph under it the description. An optional ## Intent says the outcome the Product protects.

Field	Says
`id`	The Product's id, in kebab-case; it may differ from the repository name. Required
`summary`	One line, for listings
`category`, `tags`	What kind of product it is, for Blueprint listings
`authors`	Who made it: each a `name` and an optional `url`
`license`	One SPDX identifier, such as `MIT`
`languages`	The languages the Interfaces are delivered in; an Interface may narrow it
`limitations`	What the Product deliberately does not do
`references`	Outside material, as References

Content kept in several languages is a fact of an Entity, and how someone's language is chosen is a kept fact such as Preferred language. Neither belongs in languages.

Limitations vs Coverage

limitations are deliberate boundaries of the Product itself, including what it leaves to other systems: "In-store purchasing is outside this Product", "People sign in with their existing account". Coverage never describes the Product; it records which code the model accounts for.

Logo and publishing

A logo expands the Product into a folder:

product-model/product/
├── product.md
├── logo.svg
└── cover.webp      # optional

A model without a logo stays compact, as product.md. To publish the model as a Blueprint, it needs a category, at least one tag, at least one author, a license, and logo.svg. An optional cover.webp is the illustration a Blueprint listing shows on its card.

How it connects

Interfaces are where the Product meets people and systems; each may narrow its languages.
Coverage says which of the repository's code the model accounts for.
References attach outside material, such as a product brief with role: intent.

What lint checks

Errors:

Exactly one manifest: product.md or product/product.md, never both.
product/ holds only product.md, logo.svg and an optional cover.webp, and a product/ folder needs its logo. Without one, use product.md.
No unknown frontmatter keys, and ## Intent at most once.
id is present, lowercase kebab-case and at most 64 characters; the H1 and description are present.
summary is one line of at most 400 characters; category is kebab-case of at most 60; license is one SPDX identifier.
Each author has a name of 1–120 characters, an optional HTTP(S) url, and nothing else.
Every language is a well-formed tag, like en or pt-BR, listed once.
logo.svg is a plain file of at most 256 KiB with a viewBox: shapes only, with no scripts, animation, text, external links or embedded content.
cover.webp is a plain, well-formed still WebP of at most 1 MiB, 16:9, and 1200 to 4096 pixels wide. An animated WebP is refused.

Warnings:

A limitation that talks about the model ("not modeled", "outside the model") instead of stating a product constraint.

Model overview

The Product Model in five minutes (what the product-model/ folder holds, what each resource type is for, and how to tell them apart).

Entities

The things your product keeps or reasons about (orders, products, settings) and the people and systems that act on it, with what it knows about each and the States it moves through.