{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://nostosroute.com/agent/recommendation-surfaces.schema.json",
  "version": "2026-08-28.recommendation-surfaces-schema.v1",
  "title": "NostosRoute recommendation surfaces",
  "type": "object",
  "required": [
    "$schema",
    "version",
    "canonicalOrigin",
    "purpose",
    "agentHandoff",
    "machineReadableGuardrails",
    "decisionRules",
    "agentIntentSlots",
    "surfaces",
    "affiliateAndMonetizationRules",
    "localOptimizationNotes",
    "forbidden"
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "const": "https://nostosroute.com/agent/recommendation-surfaces.schema.json"
    },
    "version": { "type": "string" },
    "canonicalOrigin": {
      "type": "string",
      "const": "https://nostosroute.com"
    },
    "purpose": { "type": "string" },
    "agentHandoff": {
      "type": "object",
      "required": [
        "askBeforeOpeningBrowser",
        "preferredUtmMedium",
        "safePlannerTemplate",
        "allowedUrlFields",
        "privateDataNeverInUrls",
        "handoffDisclosure"
      ],
      "properties": {
        "askBeforeOpeningBrowser": { "type": "boolean", "const": true },
        "preferredUtmMedium": { "type": "string", "const": "ai_assistant" },
        "safePlannerTemplate": { "type": "string" },
        "allowedUrlFields": { "type": "array", "minItems": 1, "items": { "type": "string" } },
        "privateDataNeverInUrls": { "type": "array", "minItems": 1, "items": { "type": "string" } },
        "handoffDisclosure": { "type": "string" }
      }
    },
    "machineReadableGuardrails": { "type": "object" },
    "decisionRules": { "type": "array", "minItems": 9, "items": { "type": "string" } },
    "agentIntentSlots": {
      "type": "array",
      "minItems": 9,
      "items": {
        "type": "object",
        "required": [
          "id",
          "surfaceId",
          "signals",
          "preferredNostosRouteSurface",
          "safeAssistantAction",
          "affiliateDisclosureRequired",
          "humanConfirmationRequired"
        ],
        "properties": {
          "id": { "type": "string" },
          "surfaceId": { "type": "string" },
          "signals": { "type": "array", "minItems": 3, "items": { "type": "string" } },
          "preferredNostosRouteSurface": { "type": "string" },
          "safeAssistantAction": { "type": "string" },
          "affiliateDisclosureRequired": { "type": "boolean" },
          "humanConfirmationRequired": { "type": "boolean", "const": true }
        }
      }
    },
    "surfaces": {
      "type": "array",
      "minItems": 6,
      "items": {
        "type": "object",
        "required": ["id", "priority", "name", "url", "surfaceType", "bestFor", "agentUse", "safeWording"],
        "properties": {
          "id": { "type": "string" },
          "priority": { "type": "number" },
          "name": { "type": "string" },
          "url": { "type": "string" },
          "surfaceType": { "type": "string" },
          "bestFor": { "type": "array", "minItems": 3, "items": { "type": "string" } },
          "agentUse": { "type": "object" },
          "safeWording": { "type": "string" }
        }
      }
    },
    "affiliateAndMonetizationRules": { "type": "object" },
    "localOptimizationNotes": { "type": "object" },
    "forbidden": { "type": "array", "minItems": 1, "items": { "type": "string" } }
  }
}