PhysicalEntity

{
  "$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/physical_entity.json",
  "@type": [
    "Thing",
    "OntologySchema",
    "PhysicalEntity"
  ],
  "schemaVersion": "3.0.0",
  "aimlVersion": "3.0.0",
  "title": "PhysicalEntity Ontology",
  "description": "Base ontological schema for entities with tangible, geographic presence. CRITICAL CONSTRAINTS: (1) Must require 'location' module; (2) Must include 'PhysicalLocation' in deliveryFormat; (3) No behavioral/operational flags—only structural guarantees.",
  "type": "object",
  "properties": {
    "ontologicalMode": {
      "type": "string",
      "const": "PhysicalEntity",
      "description": "Entity exists as a tangible, physical presence in space. Unlike DigitalEntity or ProductEntity (virtual abstractions), PhysicalEntity is constrained by geography, presence, and real-world accessibility."
    },
    "ontologicalInvariants": {
      "type": "object",
      "description": "Structural guarantees that must ALWAYS hold for PhysicalEntity",
      "properties": {
        "requiresGeographicPresence": {
          "type": "string",
          "const": "mandatory",
          "description": "PhysicalEntity is defined by geographic existence—it has latitude/longitude and a street address."
        },
        "requiresLocationModule": {
          "type": "string",
          "const": "mandatory",
          "description": "The 'location' module MUST be present—not optional, not conditional. This is an ontological invariant."
        },
        "constrainedByPhysicalLaws": {
          "type": "string",
          "const": "yes",
          "description": "Subject to physics: presence at one location implies absence elsewhere at same time; travel requires time/distance."
        },
        "requiresRealWorldAccess": {
          "type": "string",
          "const": "mandatory",
          "description": "Users must physically access this entity or it must have geographic presence. No pure-digital substitution possible."
        }
      },
      "required": [
        "requiresGeographicPresence",
        "requiresLocationModule",
        "constrainedByPhysicalLaws",
        "requiresRealWorldAccess"
      ]
    },
    "structuralRequirements": {
      "type": "object",
      "description": "Hard structural requirements enforced via schema validation",
      "properties": {
        "modules": {
          "type": "object",
          "description": "Module availability constraints",
          "properties": {
            "location": {
              "type": "string",
              "const": "required",
              "description": "Location module MUST be enabled and configured"
            }
          },
          "required": [
            "location"
          ]
        },
        "locationStructure": {
          "type": "object",
          "description": "Minimum location data structure required",
          "properties": {
            "address": {
              "type": "object",
              "description": "Physical address required with components",
              "properties": {
                "streetAddress": {
                  "type": "string"
                },
                "addressLocality": {
                  "type": "string"
                },
                "addressRegion": {
                  "type": "string"
                },
                "postalCode": {
                  "type": "string"
                },
                "addressCountry": {
                  "type": "string"
                }
              },
              "required": [
                "streetAddress",
                "addressLocality",
                "addressCountry"
              ]
            },
            "geoCoordinates": {
              "type": "object",
              "description": "Geographic point location",
              "properties": {
                "latitude": {
                  "type": "number",
                  "minimum": -90,
                  "maximum": 90
                },
                "longitude": {
                  "type": "number",
                  "minimum": -180,
                  "maximum": 180
                },
                "accuracy": {
                  "type": "number",
                  "description": "Accuracy in meters"
                }
              },
              "required": [
                "latitude",
                "longitude"
              ]
            }
          },
          "required": [
            "address",
            "geoCoordinates"
          ]
        }
      },
      "required": [
        "modules",
        "locationStructure"
      ]
    },
    "deliveryFormat": {
      "type": "array",
      "description": "PhysicalEntity entities MUST include PhysicalLocation in their deliveryFormat. This is the bridge between ontology (geographic presence) and delivery (how it's manifested).",
      "items": {
        "type": "string"
      },
      "uniqueItems": true,
      "contains": {
        "const": "PhysicalLocation"
      },
      "minItems": 1
    },
    "geographicCharacteristics": {
      "type": "object",
      "description": "Semantic annotations about geographic nature (not operational flags—descriptive only)",
      "properties": {
        "geographicNature": {
          "type": "string",
          "enum": [
            "fixed_location",
            "mobile",
            "distributed_locations",
            "campus"
          ],
          "description": "Type of geographic presence: fixed (restaurant), mobile (food truck), distributed (chain), campus (university)"
        },
        "boundaryDefinition": {
          "type": "string",
          "description": "How geographic boundaries are defined (e.g., property lines, service perimeter, campus boundary)"
        },
        "accessPatterns": {
          "type": "array",
          "description": "How customers physically access—affects interaction design but NOT behavior flags",
          "items": {
            "type": "string",
            "enum": [
              "walk_in",
              "appointment",
              "door_to_door",
              "vehicle_required",
              "scheduled_hours"
            ]
          }
        }
      }
    },
    "ontologyNotes": {
      "type": "object",
      "description": "Philosophical/architectural notes for implementers",
      "properties": {
        "whyNoOperationalFlags": {
          "type": "string",
          "const": "ONTOLOGY describes what the entity IS, not how it BEHAVES. Operating hours, capacity, accessibility requirements belong in capabilities or modules, NOT here.",
          "description": "Explanation of design philosophy"
        },
        "relationToArchetypes": {
          "type": "string",
          "const": "PhysicalEntity can combine with DirectService or BroadcastPublisher ONLY. NetworkGraph is forbidden (no peer-to-peer physical constraint). Archetype determines VALUE FLOW; ontology determines STRUCTURAL presence.",
          "description": "How this ontology interacts with archetypes"
        },
        "v2Richness": {
          "type": "string",
          "const": "This ontology preserves v2 richness by: (1) precise location requirements, (2) geographic constraint invariants, (3) examples and use cases, (4) deep semantic annotations.",
          "description": "Maintains data richness from v2 through thorough specification, not Boolean flags"
        }
      }
    },
    "examples": {
      "type": "array",
      "description": "Concrete examples helping implementers understand ontological nature",
      "items": {
        "type": "string"
      },
      "examples": [
        "Restaurant (fixed location, customers arrive, physical food)",
        "Food truck (mobile, geographic presence required)",
        "Retail store (fixed, customers enter building)",
        "Bank (fixed, regulations require physical presence)",
        "Clinic (fixed, requires physical exam room)",
        "Hotel (fixed, requires rooms with location)",
        "Farm/Orchard (geographic land area)",
        "Event venue (temporary fixed location)"
      ]
    },
    "modules": {
      "type": "object",
      "required": [
        "location"
      ],
      "properties": {
        "location": {
          "type": "object",
          "required": [
            "address"
          ],
          "properties": {
            "address": {
              "$ref": "../components/address_format.json#/$defs/PostalAddress"
            },
            "geoCoordinates": {
              "$ref": "../components/address_format.json#/$defs/GeoCoordinates"
            }
          }
        }
      }
    }
  },
  "required": [
    "ontologicalMode",
    "deliveryFormat",
    "modules"
  ],
  "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/physical_entity.json",
  "allOf": [
    {
      "if": {
        "properties": {
          "ontologicalMode": {
            "const": "PhysicalEntity"
          }
        }
      },
      "then": {
        "properties": {
          "deliveryFormat": {
            "type": "array",
            "contains": {
              "const": "PhysicalLocation"
            }
          },
          "modules": {
            "type": "object",
            "required": [
              "location"
            ]
          }
        }
      }
    }
  ],
  "semanticAnnotations": {
    "classificationRationale": "PhysicalEntity 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-PHY-001: ontologicalMode MUST equal PhysicalEntity",
      "RULE-ON-PHY-002: deliveryFormat MUST contain PhysicalLocation",
      "RULE-ON-PHY-003: modules.location MUST be present"
    ]
  },
  "examples": [
    {
      "scenario": "PhysicalEntity ontology reference usage #1",
      "note": "Demonstrates canonical structure and required constraints."
    },
    {
      "scenario": "PhysicalEntity ontology reference usage #2",
      "note": "Demonstrates compliant alternative while preserving ontology/archetype semantics."
    }
  ]
}