# Gift Shop Integration Guide

**Version**: 1.0  
**Date**: 2025-11-29  
**Status**: Complete

## Overview

The GiftShop class models retail operations associated with heritage custodians, including museum shops, archive bookshops, library retail spaces, and online stores.

## Schema Files

| File | Purpose |
|------|---------|
| `schemas/20251121/linkml/modules/classes/GiftShop.yaml` | Main GiftShop class definition |
| `schemas/20251121/linkml/modules/enums/GiftShopTypeEnum.yaml` | Shop type classification |
| `schemas/20251121/linkml/modules/enums/ProductCategoryEnum.yaml` | Product category enumeration |

## Architecture

```
Custodian (hub)
    │
    ├── gift_shop → GiftShop[]
    │       │
    │       ├── physical_location → AuxiliaryPlace (RETAIL_SPACE)
    │       │       └── street_address, city, opening_hours
    │       │
    │       ├── online_shop → AuxiliaryDigitalPlatform (WEBSHOP)
    │       │       └── platform_url, e-commerce details
    │       │
    │       ├── product_categories → ProductCategoryEnum[]
    │       │       └── POSTCARDS, PUZZLES, BOOKS, MEMBERSHIP_CARDS, etc.
    │       │
    │       └── business_metrics
    │               └── annual_revenue, visitor_conversion_rate, staff_count
    │
    └── (other custodian aspects: legal_status, collections, etc.)
```

## Shop Types (GiftShopTypeEnum)

| Type | Description | Example |
|------|-------------|---------|
| `MUSEUM_SHOP` | General museum merchandise | Rijksmuseum Shop |
| `BOOKSHOP` | Primarily books and publications | British Library Bookshop |
| `DESIGN_STORE` | Design objects and reproductions | MoMA Design Store |
| `SPECIALTY_SHOP` | Themed or collection-specific | V&A Jewellery Gallery Shop |
| `POP_UP` | Temporary retail for exhibitions | Vermeer Exhibition Shop |
| `KIOSK` | Small-format retail point | Museum entrance kiosk |
| `ONLINE_ONLY` | E-commerce without physical presence | Digital-only shops |
| `CAFE_SHOP` | Combined cafe and retail | Museum cafe gift corner |
| `CHILDREN_SHOP` | Focused on children's products | Science museum kids store |
| `PUBLICATION_CENTER` | Institutional publications | Archive publications office |

## Product Categories (ProductCategoryEnum)

### Core Categories

| Category | Description |
|----------|-------------|
| `REPRODUCTIONS` | Art prints, replicas, facsimiles |
| `BOOKS` | Catalogs, guides, scholarly works |
| `DESIGN_OBJECTS` | Home decor, designer items |
| `JEWELRY` | Inspired by collection pieces |
| `TEXTILES` | Clothing, scarves, bags |
| `STATIONERY` | Cards, notebooks, pens |
| `TOYS` | Educational toys, games |
| `FOOD` | Specialty foods, chocolates |
| `SOUVENIRS` | Keychains, magnets, tourist items |

### Common Museum Shop Items

| Category | Description |
|----------|-------------|
| `POSTCARDS` | Individual and sets (staple item) |
| `POSTERS` | Large format art prints |
| `PUZZLES` | Jigsaw puzzles (50-1000+ pieces) |
| `MEMBERSHIP_CARDS` | Museumkaart, annual passes |
| `MAGNETS` | Refrigerator magnets |
| `CALENDARS` | Wall, desk, advent calendars |
| `MUGS_DRINKWARE` | Coffee mugs, water bottles |
| `UMBRELLAS` | Art print umbrellas |
| `BAGS_ACCESSORIES` | Tote bags, pouches, lanyards |
| `EXHIBITION_MERCHANDISE` | Limited-edition exhibition items |
| `EDUCATIONAL_MATERIALS` | Activity books, flashcards |
| `GIFT_VOUCHERS` | Gift cards, experience vouchers |

### Specialized Categories

| Category | Description |
|----------|-------------|
| `ORIGINAL_ART` | Limited editions, artist multiples |
| `ANTIQUES` | Vintage items, period objects |
| `PLANTS` | Heritage seeds, botanical items |
| `CRAFT_SUPPLIES` | Art supplies, creative tools |
| `ACCESSIBILITY_ITEMS` | Tactile models, large print |
| `MULTIMEDIA` | DVDs, audio guides, apps |
| `GIFTS` | Curated gift sets |
| `HOME_DECOR` | Pillows, tableware, decorative items |

## Physical Location Integration

Gift shops can link to `AuxiliaryPlace` instances for physical locations:

```yaml
GiftShop:
  shop_name: "Rijksmuseum Shop"
  physical_location:
    - place_name: "Rijksmuseum Shop - Main Hall"
      auxiliary_place_type: RETAIL_SPACE  # New type added
      street_address: "Museumstraat 1"
      city: "Amsterdam"
      postal_code: "1071 XX"
```

### New AuxiliaryPlaceTypeEnum Values

Added to support gift shop locations:

| Type | Description |
|------|-------------|
| `RETAIL_SPACE` | Gift shop, bookshop, museum store |
| `CAFE_RESTAURANT` | Food service facilities |

## Online Shop Integration

Gift shops can link to `AuxiliaryDigitalPlatform` instances for e-commerce:

```yaml
GiftShop:
  shop_name: "Rijksmuseum Online Shop"
  online_shop:
    - platform_name: "Rijksmuseum Online Shop"
      platform_url: "https://www.rijksmuseumshop.nl/"
      auxiliary_platform_type: WEBSHOP  # Existing type
```

## Business Metrics

The GiftShop class captures key retail metrics:

| Slot | Type | Description |
|------|------|-------------|
| `annual_revenue` | string | Annual sales (e.g., "EUR 5,000,000") |
| `visitor_conversion_rate` | float | % of visitors who purchase (0.25 = 25%) |
| `staff_count` | integer | Number of shop employees |
| `square_meters` | float | Retail floor space |
| `price_range` | string | Price level ($, $$, $$$, $$$$) |
| `price_currency` | string | ISO 4217 code (EUR, USD, GBP) |

## Management Structure

Track whether shop is operated in-house or outsourced:

```yaml
GiftShop:
  managed_by: "In-house (Rijksmuseum BV)"
  # OR
  managed_by: "Outsourced (Culture Shops Ltd)"
```

## Temporal Validity

Track shop lifecycle with `valid_from` and `valid_to`:

```yaml
# Permanent shop
GiftShop:
  shop_name: "Rijksmuseum Shop"
  valid_from: "2013-04-13"  # Opened with renovated building
  valid_to: null  # Still operational

# Pop-up shop
GiftShop:
  shop_name: "Vermeer Exhibition Pop-up"
  shop_type: POP_UP
  valid_from: "2023-02-10"
  valid_to: "2023-06-04"  # Closed when exhibition ended
```

## Complete Example

```yaml
Custodian:
  hc_id: "https://nde.nl/ontology/hc/nl-nh-ams-m-rm-q190804"
  preferred_label: "Rijksmuseum"
  
  gift_shop:
    - shop_id: "https://nde.nl/ontology/hc/gift-shop/rijksmuseum-shop"
      shop_name: "Rijksmuseum Shop"
      shop_type: MUSEUM_SHOP
      shop_description: >-
        Award-winning museum shop offering reproductions, design objects,
        books, and exclusive Rijksmuseum merchandise.
      
      physical_location:
        - place_name: "Rijksmuseum Shop - Main Hall"
          auxiliary_place_type: RETAIL_SPACE
          street_address: "Museumstraat 1"
          postal_code: "1071 XX"
          city: "Amsterdam"
      
      online_shop:
        - platform_name: "Rijksmuseum Online Shop"
          platform_url: "https://www.rijksmuseumshop.nl/"
          auxiliary_platform_type: WEBSHOP
      
      product_categories:
        - REPRODUCTIONS
        - POSTERS
        - POSTCARDS
        - PUZZLES
        - BOOKS
        - DESIGN_OBJECTS
        - JEWELRY
        - HOME_DECOR
        - MEMBERSHIP_CARDS
        - EXHIBITION_MERCHANDISE
      
      price_currency: EUR
      price_range: "$$"
      
      accepts_payment_methods:
        - CASH
        - CREDIT_CARD
        - DEBIT_CARD
        - MOBILE_PAYMENT
        - MUSEUM_CARD
      
      opening_hours: "Mo-Su 09:00-18:00"
      staff_count: 25
      square_meters: 450.0
      visitor_conversion_rate: 0.35
      
      managed_by: "In-house (Rijksmuseum BV)"
      valid_from: "2013-04-13"
      
      refers_to_custodian: "https://nde.nl/ontology/hc/nl-nh-ams-m-rm-q190804"
```

## Schema.org Alignment

| LinkML Class/Slot | Schema.org Mapping |
|-------------------|-------------------|
| `GiftShop` | `schema:Store` |
| `shop_name` | `schema:name` |
| `physical_location` | `schema:location` |
| `online_shop` | `schema:url` |
| `product_categories` | `schema:category` |
| `price_currency` | `schema:priceCurrency` |
| `price_range` | `schema:priceRange` |
| `accepts_payment_methods` | `schema:paymentAccepted` |
| `opening_hours` | `schema:openingHours` |
| `annual_revenue` | `schema:annualRevenue` |
| `staff_count` | `schema:numberOfEmployees` |
| `square_meters` | `schema:floorSize` |
| `refers_to_custodian` | `schema:parentOrganization` |

## GoodRelations Integration

For detailed product/offer modeling, GiftShop aligns with GoodRelations:

| Concept | GoodRelations URI |
|---------|-------------------|
| Business Entity | `gr:BusinessEntity` |
| Product Offering | `gr:Offering` |
| Payment Methods | `gr:PaymentMethod` |

## Use Cases

### 1. Museum Retail Analysis

Query all museum shops with their product categories and conversion rates:

```sparql
SELECT ?shop ?name ?conversion WHERE {
  ?shop a schema:Store ;
        schema:name ?name ;
        hc:visitorConversionRate ?conversion .
}
ORDER BY DESC(?conversion)
```

### 2. E-commerce Platform Discovery

Find all custodians with online shops:

```sparql
SELECT ?custodian ?shopUrl WHERE {
  ?custodian hc:gift_shop ?shop .
  ?shop hc:online_shop ?platform .
  ?platform hc:platform_url ?shopUrl .
}
```

### 3. Temporary Retail Tracking

Find pop-up shops for exhibitions:

```sparql
SELECT ?shop ?name ?start ?end WHERE {
  ?shop a schema:Store ;
        hc:shop_type "POP_UP" ;
        schema:name ?name ;
        schema:validFrom ?start ;
        schema:validThrough ?end .
}
```

## Related Documentation

- [SCHEMA_MODULES.md](SCHEMA_MODULES.md) - Overall schema architecture
- [AuxiliaryPlace class](../schemas/20251121/linkml/modules/classes/AuxiliaryPlace.yaml) - Physical location modeling
- [AuxiliaryDigitalPlatform class](../schemas/20251121/linkml/modules/classes/AuxiliaryDigitalPlatform.yaml) - Digital platform modeling

---

**Last Updated**: 2025-11-29  
**Schema Version**: 20251121