DirectService

{
  "$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/archetypes/direct_service.json",
  "@type": [
    "Thing",
    "ArchetypeSchema",
    "DirectService"
  ],
  "schemaVersion": "3.0.0",
  "aimlVersion": "3.0.0",
  "title": "DirectService Interaction Archetype",
  "description": "Platform provides value directly to user/consumer (1:1 or 1:many relationship). Platform creates, owns, or curates value; users consume directly. No intermediation, no peer-to-peer. This is the most common archetype used by physical businesses, SaaS tools, utilities, and any platform where the value proposition IS the platform itself.",
  "type": "object",
  "properties": {
    "interactionArchetype": {
      "type": "array",
      "description": "DirectService archetype indicator. Current v3 canonical rule: exactly one archetype per entity schema.",
      "contains": {
        "const": "DirectService"
      },
      "items": {
        "type": "string",
        "enum": [
          "DirectService",
          "MediatedExchange",
          "NetworkGraph",
          "BroadcastPublisher",
          "ProtocolSystem"
        ]
      },
      "minItems": 1,
      "maxItems": 1
    },
    "structuralMetadata": {
      "type": "object",
      "description": "Core structural characteristics of DirectService. Fields marked IMMUTABLE must not be overridden by entity schemas.",
      "properties": {
        "topology": {
          "type": "string",
          "const": "binary",
          "description": "IMMUTABLE. Binary topology: Platform ↔ User. No triadic intermediation. Contrast: MediatedExchange=triadic, NetworkGraph=many-to-many."
        },
        "roles": {
          "type": "array",
          "description": "IMMUTABLE. Exactly two roles: platform (value creator) and user (value consumer). No broker/intermediary role exists.",
          "items": {
            "type": "string",
            "enum": [
              "platform",
              "user"
            ]
          },
          "minItems": 2,
          "maxItems": 2,
          "uniqueItems": true,
          "const": [
            "user",
            "platform"
          ]
        },
        "valueSource": {
          "type": "string",
          "const": "platform_provided",
          "description": "IMMUTABLE. Platform is the primary value source. Platform creates, curates, or owns the delivered value. Distinguish from NetworkGraph where users generate value."
        },
        "valueFlowDirection": {
          "type": "string",
          "enum": [
            "platform_to_user",
            "platform_to_many_users"
          ],
          "description": "Direction of primary value flow. 'platform_to_user' for individual sessions; 'platform_to_many_users' for broadcast-style delivery."
        },
        "transactionFlow": {
          "type": "string",
          "const": "direct",
          "description": "IMMUTABLE. No intermediation layer: platform delivers directly to consumer. No escrow, no third-party settlement."
        },
        "networkEffects": {
          "type": "string",
          "const": "none",
          "description": "IMMUTABLE. No meaningful network effects — one user's presence does not increase value for other users. Core distinction from NetworkGraph."
        },
        "contentOwnership": {
          "type": "string",
          "enum": [
            "platform",
            "users",
            "licensed"
          ],
          "description": "Who owns the content/value. Pure DirectService: 'platform'. UGC-heavy: 'users' (consider NetworkGraph). 3rd-party licensed: 'licensed'."
        },
        "scalabilityModel": {
          "type": "string",
          "enum": [
            "per_seat",
            "per_usage",
            "flat_capacity",
            "elastic"
          ],
          "description": "How service scales with user growth (informational — not SDK-enforced)."
        }
      },
      "required": [
        "topology",
        "roles",
        "valueSource",
        "transactionFlow"
      ]
    },
    "requiredCapabilities": {
      "type": "array",
      "description": "Mandatory capability groups. SDK v3 validates that entities claiming DirectService have at minimum the 'interaction' group populated.",
      "items": {
        "type": "string",
        "enum": [
          "interaction",
          "content",
          "commerce",
          "financial",
          "booking",
          "location",
          "amenities",
          "community",
          "media",
          "ai",
          "communication"
        ]
      },
      "uniqueItems": true,
      "minItems": 1,
      "contains": {
        "const": "interaction"
      }
    },
    "compatibleOntologicalModes": {
      "type": "array",
      "description": "Ontological modes that may declare DirectService archetype.",
      "items": {
        "type": "string"
      },
      "examples": [
        "PhysicalEntity",
        "DigitalEntity",
        "FinancialEntity",
        "EventEntity"
      ]
    },
    "disambiguationRules": {
      "type": "object",
      "description": "Classification guidance to distinguish DirectService from adjacent archetypes — the most common source of classification errors.",
      "properties": {
        "vsNetworkGraph": {
          "type": "string",
          "description": "If users generate primary value (UGC, social connections) → NetworkGraph. If platform generates value (tools, storage) → DirectService. YouTube=DirectService (tool). Facebook=NetworkGraph (user connections/content)."
        },
        "vsBroadcastPublisher": {
          "type": "string",
          "description": "Primary value is FUNCTIONALITY/CAPABILITY → DirectService. Primary value is CONTENT/INFORMATION → BroadcastPublisher. Google Drive=DirectService. NYT=BroadcastPublisher. Netflix=BroadcastPublisher. Shopify=DirectService."
        },
        "vsMediatedExchange": {
          "type": "string",
          "description": "Platform IS the service provider → DirectService. Platform CONNECTS third-party buyers and sellers → MediatedExchange. Restaurant=DirectService. Uber=MediatedExchange."
        }
      }
    },
    "semanticAnnotations": {
      "type": "object",
      "description": "Semantic metadata for machine understanding of this DirectService instance.",
      "properties": {
        "primaryValueProposition": {
          "type": "string",
          "enum": [
            "capability",
            "access",
            "processing",
            "storage",
            "delivery",
            "support",
            "healthcare",
            "hospitality"
          ],
          "description": "What kind of direct value the platform provides to users."
        },
        "serviceDeliveryModel": {
          "type": "string",
          "enum": [
            "on_demand",
            "scheduled",
            "subscription",
            "event_based",
            "real_time"
          ],
          "description": "When/how service is delivered."
        },
        "userSessionType": {
          "type": "string",
          "enum": [
            "transient",
            "persistent",
            "stateful",
            "one_time"
          ],
          "description": "Nature of the user-platform interaction session."
        }
      }
    },
    "governanceMetadata": {
      "type": "object",
      "description": "Governance and lifecycle tracking for this archetype schema definition.",
      "properties": {
        "archetypeVersion": {
          "type": "string",
          "const": "3.0.0"
        },
        "introducedIn": {
          "type": "string",
          "const": "META-AIML v3.0.0"
        },
        "stabilityLevel": {
          "type": "string",
          "const": "stable",
          "description": "DirectService is the foundational archetype — stable and well-understood across all entity types."
        },
        "sdkValidationRules": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "SDK v3 rules enforced when validating an entity that declares DirectService.",
          "examples": [
            "RULE-DS-001: interactionArchetype array MUST contain 'DirectService'",
            "RULE-DS-002: structuralMetadata.topology MUST equal 'binary'",
            "RULE-DS-003: structuralMetadata.valueSource MUST equal 'platform_provided'",
            "RULE-DS-004: structuralMetadata.networkEffects MUST equal 'none'",
            "RULE-DS-005: capabilities.interaction MUST be present and non-empty",
            "RULE-DS-006: ProductEntity MUST NOT declare DirectService (no archetype allowed)",
            "RULE-DS-007: If contentOwnership='platform' and value is editorial → WARN: consider BroadcastPublisher"
          ]
        }
      }
    },
    "examples": {
      "type": "array",
      "description": "Canonical DirectService usage examples with ontological mode and rationale.",
      "items": {
        "type": "object",
        "properties": {
          "entityName": {
            "type": "string"
          },
          "ontologicalMode": {
            "type": "string"
          },
          "domain": {
            "type": "string"
          },
          "rationale": {
            "type": "string"
          }
        }
      },
      "examples": [
        {
          "entityName": "Restaurant",
          "ontologicalMode": "PhysicalEntity",
          "domain": "Hospitality",
          "rationale": "Restaurant prepares food → customers eat. Platform provides value directly. No peer-to-peer exchange."
        },
        {
          "entityName": "Google Drive",
          "ontologicalMode": "DigitalEntity",
          "domain": "Technology",
          "rationale": "Platform provides storage capability. The SERVICE (storage, sync, access) is platform-provided even if content is user-uploaded."
        },
        {
          "entityName": "Online Banking",
          "ontologicalMode": "FinancialEntity",
          "domain": "Finance",
          "rationale": "Bank provides financial services directly to customer. No intermediation. Classic DirectService for FinancialEntity."
        },
        {
          "entityName": "Clinic",
          "ontologicalMode": "PhysicalEntity",
          "domain": "Healthcare",
          "rationale": "Doctors provide medical care directly to patients. Binary relationship: clinic ↔ patient."
        },
        {
          "entityName": "SaaS Task Manager",
          "ontologicalMode": "DigitalEntity",
          "domain": "Productivity",
          "rationale": "Platform provides project management functionality. Workspaces are independent — no cross-user network value."
        },
        {
          "entityName": "Hotel",
          "ontologicalMode": "PhysicalEntity",
          "domain": "Hospitality",
          "rationale": "Hotel provides accommodation directly to guests. Physical location required. Guest ↔ Hotel binary relationship."
        }
      ]
    }
  },
  "required": [
    "interactionArchetype",
    "structuralMetadata"
  ],
  "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/archetypes/direct_service.json",
  "allOf": [
    {
      "if": {
        "properties": {
          "interactionArchetype": {
            "contains": {
              "const": "DirectService"
            }
          }
        }
      },
      "then": {
        "required": [
          "capabilities"
        ],
        "properties": {
          "capabilities": {
            "type": "object",
            "required": [
              "interaction"
            ],
            "properties": {
              "interaction": {
                "$ref": "../components/capability_groups.json#/$defs/InteractionCapabilities"
              }
            }
          }
        }
      }
    }
  ],
  "semanticAnnotations": {
    "classificationRationale": "DirectService archetype 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-AR-DIRECT-001: interactionArchetype MUST contain DirectService",
      "RULE-AR-DIRECT-002: structuralMetadata const fields MUST match archetype definition",
      "RULE-AR-DIRECT-003: capabilities MUST include interaction"
    ]
  },
  "examples": [
    {
      "scenario": "DirectService archetype reference usage #1",
      "note": "Demonstrates canonical structure and required constraints."
    },
    {
      "scenario": "DirectService archetype reference usage #2",
      "note": "Demonstrates compliant alternative while preserving ontology/archetype semantics."
    }
  ]
}