{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "@context": [
    "https://schemas.meta-aiml.org/v3.0.0/context.jsonld"
  ],
  "@id": "https://schemas.meta-aiml.org/v3.0.0/entity/store.json",
  "$id": "https://schemas.meta-aiml.org/v3.0.0/entity/store.json",
  "@type": "Store",
  "schemaVersion": "3.0.0",
  "aimlVersion": "3.0.0",
  "title": "Store Entity Schema",
  "description": "v3 schema for physical retail stores as static website intelligence profile: durable store metadata plus external source links for dynamic catalog/review data.",
  "examples": [
    {
      "description": "Neighborhood grocery store with in-store checkout and curbside pickup",
      "reference": "store_example_grocery"
    },
    {
      "description": "Specialty retail store with membership discounts and digital catalog lookup",
      "reference": "store_example_specialty_retail"
    }
  ],
  "type": "object",
  "additionalProperties": false,
  "allOf": [
    {
      "$ref": "../ontology/physical_entity.json"
    },
    {
      "$ref": "../archetypes/direct_service.json"
    }
  ],
  "properties": {
    "@type": {
      "const": "Store"
    },
    "ontologicalMode": {
      "const": "PhysicalEntity"
    },
    "interactionArchetype": {
      "type": "array",
      "contains": {
        "const": "DirectService"
      },
      "items": {
        "type": "string",
        "enum": [
          "DirectService"
        ]
      }
    },
    "domain": {
      "const": "Retail"
    },
    "businessModel": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Transactional",
          "Membership",
          "Subscription"
        ]
      }
    },
    "deliveryFormat": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "PhysicalLocation",
          "WebApp",
          "MobileApp"
        ]
      },
      "contains": {
        "const": "PhysicalLocation"
      }
    },
    "name": {
      "$ref": "../components/multilingual_format.json#/$defs/LocalizedText"
    },
    "description": {
      "$ref": "../components/multilingual_format.json#/$defs/LocalizedText"
    },
    "shortDescription": {
      "$ref": "../components/multilingual_format.json#/$defs/LocalizedTextOrString"
    },
    "url": {
      "type": "string",
      "format": "uri"
    },
    "foundingDate": {
      "type": "string",
      "format": "date"
    },
    "properties": {
      "type": "object",
      "properties": {
        "storeFormat": {
          "type": "string",
          "enum": [
            "grocery",
            "department",
            "specialty",
            "convenience",
            "showroom"
          ]
        },
        "assortmentBreadth": {
          "type": "string",
          "enum": [
            "narrow",
            "moderate",
            "broad"
          ]
        },
        "supportsInStorePickup": {
          "type": "boolean"
        },
        "supportsCurbsidePickup": {
          "type": "boolean"
        },
        "supportsReturnsAtStore": {
          "type": "boolean"
        },
        "averageFootfallPerDay": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "capabilities": {
      "type": "object",
      "required": [
        "interaction"
      ],
      "properties": {
        "commerce": {
          "$ref": "../components/capability_groups.json#/$defs/CommerceCapabilities"
        },
        "financial": {
          "$ref": "../components/capability_groups.json#/$defs/FinancialCapabilities"
        },
        "interaction": {
          "$ref": "../components/capability_groups.json#/$defs/InteractionCapabilities"
        },
        "location": {
          "$ref": "../components/capability_groups.json#/$defs/LocationCapabilities"
        },
        "amenities": {
          "$ref": "../components/capability_groups.json#/$defs/AmenitiesCapabilities"
        }
      }
    },
    "modules": {
      "type": "object",
      "required": [
        "location"
      ],
      "properties": {
        "location": {
          "type": "object",
          "properties": {
            "address": {
              "$ref": "../components/address_format.json#/$defs/PostalAddress"
            },
            "geoCoordinates": {
              "$ref": "../components/address_format.json#/$defs/GeoCoordinates"
            },
            "floorMapAvailable": {
              "type": "boolean"
            }
          }
        },
        "inventory": {
          "type": "object",
          "properties": {
            "skuCount": {
              "type": "integer",
              "minimum": 0
            },
            "restockCadence": {
              "type": "string",
              "enum": [
                "daily",
                "weekly",
                "mixed"
              ]
            },
            "supportsRealtimeStockVisibility": {
              "type": "boolean"
            },
            "inventoryDiscovery": {
              "type": "object",
              "required": [
                "dataSources"
              ],
              "properties": {
                "canonicalCatalogUrl": {
                  "type": "string",
                  "format": "uri"
                },
                "dataSources": {
                  "type": "array",
                  "minItems": 1,
                  "items": {
                    "type": "object",
                    "required": [
                      "sourceType",
                      "sourceUrl",
                      "format"
                    ],
                    "properties": {
                      "sourceType": {
                        "type": "string",
                        "enum": [
                          "file_export",
                          "public_feed_page",
                          "public_api_endpoint",
                          "other"
                        ]
                      },
                      "sourceUrl": {
                        "type": "string",
                        "format": "uri"
                      },
                      "format": {
                        "type": "string",
                        "enum": [
                          "json",
                          "xml",
                          "csv",
                          "rss",
                          "html",
                          "other"
                        ]
                      },
                      "updateCadence": {
                        "type": "string",
                        "enum": [
                          "real_time",
                          "hourly",
                          "daily",
                          "weekly",
                          "manual"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "checkout": {
          "type": "object",
          "properties": {
            "selfCheckoutEnabled": {
              "type": "boolean"
            },
            "posIntegratedLoyalty": {
              "type": "boolean"
            },
            "digitalReceiptEnabled": {
              "type": "boolean"
            }
          }
        },
        "reviews": {
          "type": "object",
          "properties": {
            "ratingSources": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "object",
                "required": [
                  "provider",
                  "sourceUrl"
                ],
                "properties": {
                  "provider": {
                    "type": "string",
                    "enum": [
                      "google_business_profile",
                      "yelp",
                      "tripadvisor",
                      "opentable",
                      "facebook",
                      "custom"
                    ]
                  },
                  "sourceType": {
                    "type": "string",
                    "enum": [
                      "public_page",
                      "official_export",
                      "public_api_endpoint",
                      "other"
                    ]
                  },
                  "sourceUrl": {
                    "type": "string",
                    "format": "uri"
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "json",
                      "xml",
                      "csv",
                      "rss",
                      "html",
                      "other"
                    ]
                  },
                  "updateCadence": {
                    "type": "string",
                    "enum": [
                      "real_time",
                      "hourly",
                      "daily",
                      "weekly",
                      "manual"
                    ]
                  }
                }
              }
            },
            "retrievalPolicy": {
              "type": "object",
              "properties": {
                "requiresLiveFetch": {
                  "type": "boolean"
                },
                "recommendedRefreshHours": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "structuralMetadata": {
      "type": "object",
      "properties": {
        "topology": {
          "const": "binary"
        },
        "roles": {
          "const": [
            "user",
            "platform"
          ]
        },
        "valueSource": {
          "const": "platform_provided"
        },
        "transactionFlow": {
          "const": "direct"
        },
        "networkEffects": {
          "const": "none"
        },
        "serviceMode": {
          "type": "string",
          "enum": [
            "in_person",
            "omnichannel",
            "hybrid"
          ]
        }
      }
    },
    "targetAudience": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "siteCapabilities": {
      "type": "object",
      "properties": {
        "supportedDevices": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "desktop",
              "mobile",
              "tablet"
            ]
          }
        },
        "languages": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "accessibilityFeatures": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "@type",
    "ontologicalMode",
    "interactionArchetype",
    "domain",
    "name",
    "description",
    "deliveryFormat",
    "modules",
    "capabilities",
    "structuralMetadata"
  ],
  "validationMetadata": {
    "schemaVersion": "3.0.0",
    "phase": "entity",
    "status": "draft",
    "lastValidated": "2026-02-20T12:00:00Z",
    "validator": "META-AIML QA"
  },
  "semanticAnnotations": {
    "classificationRationale": "Store is modeled as PhysicalEntity because core value delivery depends on physical premises and local inventory availability. DirectService applies because the store transacts directly with customers.",
    "disambiguationNotes": "Different from ecommerce_store (digital direct sales) and marketplace (third-party mediation). For static website deployment, avoid embedding full product/review snapshots; use source links in modules.inventory.inventoryDiscovery and modules.reviews.ratingSources."
  },
  "governanceMetadata": {
    "entityVersion": "3.0.0",
    "introducedIn": "META-AIML v3.0.0",
    "stabilityLevel": "draft",
    "sdkValidationRules": [
      "RULE-STOR-001: @type MUST equal \"Store\"",
      "RULE-STOR-002: ontologicalMode MUST equal \"PhysicalEntity\"",
      "RULE-STOR-003: interactionArchetype MUST contain \"DirectService\"",
      "RULE-STOR-004: deliveryFormat MUST contain \"PhysicalLocation\"",
      "RULE-STOR-005: modules.location MUST be present",
      "RULE-STOR-006: capabilities.interaction MUST be present",
      "RULE-STOR-007: modules.inventory.inventoryDiscovery.dataSources MUST include sourceType/sourceUrl/format",
      "RULE-STOR-008: modules.reviews.ratingSources MUST include provider/sourceUrl when review sources are declared"
    ]
  }
}