ProductEntity

{
  "$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/ontology/product_entity.json",
  "@type": [
    "Thing",
    "OntologySchema",
    "ProductEntity"
  ],
  "schemaVersion": "3.0.0",
  "aimlVersion": "3.0.0",
  "title": "ProductEntity Ontology",
  "description": "Base ontological schema for tangible/digital products and goods. CRITICAL: (1) Products are ITEMS, not platforms; (2) NO interaction archetypes allowed; (3) Has inventory/version lifecycle; (4) Distinct from ProductEntity-hosting-platform (which would be DigitalEntity+archetype).",
  "type": "object",
  "properties": {
    "ontologicalMode": {
      "type": "string",
      "const": "ProductEntity",
      "description": "Entity is a PRODUCT/GOOD—tangible item or digital asset with inventory lifecycle. Fundamentally different from services (DirectService), platforms (DigitalEntity), or events."
    },
    "ontologicalInvariants": {
      "type": "object",
      "description": "Structural guarantees ALWAYS true for ProductEntity",
      "properties": {
        "isItem": {
          "type": "string",
          "const": "yes",
          "description": "A discrete product with identity, not an abstract service."
        },
        "hasInventoryCycle": {
          "type": "string",
          "const": "yes",
          "description": "Product has creation, distribution, stock, potential discontinuation."
        },
        "cannotBeArchetype": {
          "type": "string",
          "const": "yes",
          "description": "ProductEntity MUST NOT declare interactionArchetype. Products don't define interaction patterns—they ARE exchanged via archetypes, but don't own them."
        },
        "notAPlatform": {
          "type": "string",
          "const": "yes",
          "description": "A product is not a platform. The platform SELLING the product is separate (e.g., DigitalEntity+MediatedExchange)."
        }
      },
      "required": [
        "isItem",
        "hasInventoryCycle",
        "cannotBeArchetype",
        "notAPlatform"
      ]
    },
    "structuralRequirements": {
      "type": "object",
      "description": "Hard structural requirements",
      "properties": {
        "productIdentifiers": {
          "type": "object",
          "description": "Unique product identification (structural, not behavioral)",
          "properties": {
            "internalId": {
              "type": "string",
              "description": "Platform-specific product ID"
            },
            "standardIdentifiers": {
              "type": "array",
              "description": "Industry-standard identifiers",
              "items": {
                "type": "object",
                "properties": {
                  "idType": {
                    "type": "string",
                    "enum": [
                      "SKU",
                      "UPC",
                      "EAN",
                      "ISBN",
                      "ISSN",
                      "ASIN",
                      "DOI",
                      "UUID"
                    ]
                  },
                  "idValue": {
                    "type": "string"
                  }
                },
                "required": [
                  "idType",
                  "idValue"
                ]
              }
            }
          },
          "required": [
            "internalId"
          ]
        },
        "productType": {
          "type": "object",
          "description": "Ontological categorization of product nature",
          "properties": {
            "physicalOrDigital": {
              "type": "string",
              "enum": [
                "physical",
                "digital",
                "hybrid"
              ],
              "description": "Nature of product manifestation"
            },
            "isConsumable": {
              "type": "boolean",
              "description": "Gets consumed/used up (vs durable)"
            },
            "isVersionable": {
              "type": "boolean",
              "description": "Can have versions (software, music albums, etc.)"
            },
            "hasVariants": {
              "type": "boolean",
              "description": "Comes in variants (colors, sizes, models)"
            },
            "isRecurring": {
              "type": "boolean",
              "description": "Subscription product (recurring purchase)"
            }
          },
          "required": [
            "physicalOrDigital"
          ]
        },
        "lifecycle": {
          "type": "object",
          "description": "Product lifecycle structure (when created, version history possible)",
          "properties": {
            "creationDate": {
              "type": "string",
              "format": "date",
              "description": "When product was first created/released"
            },
            "currentVersion": {
              "type": "string",
              "description": "Latest version/edition identifier"
            },
            "discontinuationAllowed": {
              "type": "boolean",
              "const": true,
              "description": "Products can be discontinued"
            }
          },
          "required": [
            "creationDate"
          ]
        },
        "manufacturerInfo": {
          "type": "object",
          "description": "Who makes/authors the product",
          "properties": {
            "manufacturerName": {
              "type": "string"
            },
            "manufacturerCountry": {
              "type": "string"
            }
          }
        }
      },
      "required": [
        "productIdentifiers",
        "productType",
        "lifecycle"
      ]
    },
    "deliveryFormat": {
      "type": "array",
      "description": "How product is delivered/manifested (physical shipping, digital download, etc.)",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "uniqueItems": true,
      "examples": [
        "PhysicalShipment",
        "DigitalDownload",
        "StreamingAccess",
        "PhysicalPickup"
      ]
    },
    "semanticAnnotations": {
      "type": "object",
      "description": "Semantic info to help ML understand product nature",
      "properties": {
        "productCategory": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "examples": [
            "Electronics",
            "Clothing",
            "Books",
            "Software",
            "Services"
          ]
        },
        "targetAudience": {
          "type": "string",
          "enum": [
            "consumer",
            "enterprise",
            "prosumer",
            "education"
          ],
          "description": "Who the product is intended for"
        }
      }
    },
    "ontologyNotes": {
      "type": "object",
      "description": "Architectural notes",
      "properties": {
        "whyNoArchetype": {
          "type": "string",
          "const": "ONTOLOGY defines WHAT the entity IS. ProductEntity is a THING (good/product), not a SERVICE MODEL. Archetype describes how a platform DELIVERS value, but products don't deliver—they ARE DELIVERED.",
          "description": "Design philosophy"
        },
        "productVsPlatform": {
          "type": "string",
          "const": "Netflix (the platform) = DigitalEntity + BroadcastPublisher, not ProductEntity. Movies (individual items) = ProductEntity. Distinction is crucial.",
          "description": "Common confusion clarification"
        },
        "v2Richness": {
          "type": "string",
          "const": "Preserved through: detailed identifiers (SKU/UPC/ISBN), version tracking, manufacturer info, lifecycle states, delivery methods.",
          "description": "Information density maintained"
        }
      }
    },
    "examples": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "examples": [
        "Book (ISBN, versions, physical)",
        "Software license (digital, versioned, recurring)",
        "T-shirt (physical, variants in size/color)",
        "Movie (digital, downloadable)",
        "Course material (digital, updated versions)",
        "Appliance (physical, model variants)"
      ]
    },
    "productType": {
      "type": "string",
      "enum": [
        "physical",
        "digital",
        "hybrid"
      ]
    },
    "inventory": {
      "type": "object",
      "properties": {
        "availableQuantity": {
          "type": "integer",
          "minimum": 0
        },
        "stockStatus": {
          "type": "string",
          "enum": [
            "in_stock",
            "out_of_stock",
            "backorder"
          ]
        }
      },
      "required": [
        "availableQuantity",
        "stockStatus"
      ]
    }
  },
  "required": [
    "ontologicalMode",
    "deliveryFormat",
    "productType",
    "inventory"
  ],
  "validationMetadata": {
    "schemaVersion": "3.0.0",
    "phase": "phase_1",
    "status": "draft",
    "lastValidated": "2026-02-19",
    "validator": "META-AIML QA"
  },
  "$id": "https://schemas.meta-aiml.org/v3.0.0/ontology/product_entity.json",
  "allOf": [
    {
      "if": {
        "properties": {
          "ontologicalMode": {
            "const": "ProductEntity"
          }
        }
      },
      "then": {
        "not": {
          "required": [
            "interactionArchetype"
          ]
        }
      }
    }
  ],
  "semanticAnnotations": {
    "classificationRationale": "ProductEntity ontology schema aligned with META-AIML v3 structural completeness rules.",
    "disambiguationNotes": "Ontology and archetype constraints are encoded for machine-verifiable validation."
  },
  "governanceMetadata": {
    "schemaVersion": "3.0.0",
    "stabilityLevel": "draft",
    "sdkValidationRules": [
      "RULE-ON-PROD-001: ontologicalMode MUST equal ProductEntity",
      "RULE-ON-PROD-002: interactionArchetype MUST NOT be present",
      "RULE-ON-PROD-003: productType and inventory MUST be present"
    ]
  },
  "examples": [
    {
      "scenario": "ProductEntity ontology reference usage #1",
      "note": "Demonstrates canonical structure and required constraints."
    },
    {
      "scenario": "ProductEntity ontology reference usage #2",
      "note": "Demonstrates compliant alternative while preserving ontology/archetype semantics."
    }
  ]
}