Naming Conventions

Spójna konwencja nazewnictwa w storefront GraphQL API. Wprowadzona w 14.0.0 (BREAKING). Każdy nowy field MUSI follow te zasady.

1. URL identifier — zawsze `handle`

Wszystkie types używają handle: String! jako URL-friendly identifier.

Type	URL field	Example
`Product`	`handle`	`funko-pop-batman` → `/products/funko-pop-batman`
`Collection`	`handle`	`nowosci` → `/collections/nowosci`
`Category`	`handle`	`figurki` → `/categories/figurki`
`Brand`	`handle`	`funko` → `/brands/funko`
`ShopPage`	`handle`	`regulamin` → `/pages/regulamin`
`BlogPost`	`handle`	`nowa-kolekcja` → `/blog/nowa-kolekcja`
`BlogCategory`	`handle`	`news`
`BlogTag`	`handle`	`summer`
`LoyaltyReward`	`handle`	`free-shipping`
`Menu`	`handle`	`main-menu`
`AttributeDefinition`	`handle`	`kolor`
`ConfiguratorField`	`handle`	—
`CategoryFilterOption`	`handle`	—

Input filters/args też używają handle:

query { category(handle: "figurki") { id name } }
query { brand(handle: "funko") { id name } }
query Products($filters: [ProductFilter!]) { products(filters: $filters) { ... } }
# filters: [{ brand: { handle: "funko" } }]

2. Display name — `title` (content) vs `name` (entity)

Świadoma semantyka:

`title` (content/document)	`name` (entity/concept)
Product, Collection, ShopPage	Category, Brand, Shop
BlogPost, MenuItem, Menu	BlogAuthor, BlogCategory
ShippingMethod, ProductVariant	Location, TierBenefit

Reasoning: title pasuje do dokumentów/kart produktów (Product.title = "Funko Pop Batman"). name pasuje do bytów (Brand.name = "Funko", Category.name = "Figurki", Shop.name = "GameGoods").

3. Image — per-domain semantic

Field	Used by	Semantic
`image`	Category, Collection, MenuItem, BlogCategory	Single hero/thumbnail
`featuredImage` + `images[]`	Product, BlogPost	Gallery z primary
`logo`	Brand, Shop, ShopBrand	Brand mark
`avatar`	BlogAuthor	Person headshot

NIE unifikuj — każdy semantyk jest świadomy.

4. Content — domain-specific

Domain	Fields
Commerce (Product, Category, Collection, Brand)	`description(format: RichTextFormat)` — `HTML` (domyślnie) / `TEXT` / `JSON`
CMS (ShopPage)	`body(format: RichTextFormat)` + `bodySummary: String`
Article (BlogPost)	`content(format: RichTextFormat)` + `excerpt: String`

Per-domain. Pole treści przyjmuje argument format (domyślnie HTML); TEXT daje czysty tekst pod meta/summary. Szczegóły i wycofywane pola (descriptionHtml, contentFormat) — patrz Zapytania — treść rich-text.

5. Type naming

Concrete entity name (no Summary / Lite / Mini suffix). Przykład: Brand (NIE BrandSummary).
Shop prefix tylko dla tenant-scoped resources: Shop, ShopPage, ShopPolicy, ShopBranding, ShopColors, ShopFonts, ShopBrand. Disambiguates z global types (PageInfo z Relay, Brand jako product entity).

6. Admin DTO vs Storefront GraphQL

Dual naming intentional:

API	URL identifier
Admin REST API (`/v1/commerce/shops/:id/brands/...`)	`slug` (internal naming)
Storefront GraphQL (`/storefront/graphql`)	`handle` (industry-standard external)

Wewnętrznie ten identyfikator pozostaje slug — w Storefront GraphQL zawsze używasz handle, a mapowanie jest transparentne.

Dlaczego? Admin to internal API (frontend SaaS — własna konwencja). Storefront GraphQL to external API (third-party devs). Każdy ma własne audience.

1. URL identifier — zawsze handle​

2. Display name — title (content) vs name (entity)​

3. Image — per-domain semantic​

4. Content — domain-specific​

5. Type naming​

6. Admin DTO vs Storefront GraphQL​

See Also​