{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hypamoon-com/json-schema/hypamoon-com-advice-schema.json",
  "title": "Advice",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hypamoon-com-openapi.json#/components/schemas/Advice",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "webshop",
        "bookings",
        "restaurant",
        "course_membership",
        "wordpress_portal"
      ]
    },
    "title": {
      "type": "string"
    },
    "summary": {
      "type": "string"
    },
    "country": {
      "type": [
        "string",
        "null"
      ],
      "description": "The country the advice is for; null when none is known: nothing is assumed, the country question is then blocking."
    },
    "country_source": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "argument",
        "company_details",
        null
      ],
      "description": "Where the country came from: the country argument, or the project's company details (set_company_details). Null when no country is known."
    },
    "region": {
      "type": "string",
      "enum": [
        "eu",
        "uk",
        "us",
        "other"
      ],
      "description": "eu (detailed), uk and us (basics), other (a general fallback, also when no country is known)."
    },
    "audience": {
      "type": "string",
      "enum": [
        "consumers",
        "businesses",
        "both"
      ]
    },
    "how_to_use": {
      "type": "string",
      "description": "For the agent: inform yourself, ask only the blocking questions, use the defaults for the rest, and offer the checklist; never a questionnaire or a gate."
    },
    "ask_first": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "question": {
            "type": "string"
          },
          "why": {
            "type": "string"
          },
          "default": {
            "type": "string",
            "description": "What to use when the user does not know or skips the question."
          },
          "blocking": {
            "type": "boolean",
            "description": "Only these block a working result; at most two or three per type."
          }
        },
        "required": [
          "id",
          "question",
          "why",
          "default",
          "blocking"
        ]
      }
    },
    "build_plan": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "how": {
            "type": "string"
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "optional": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "title",
          "how",
          "tools"
        ]
      }
    },
    "go_live_checklist": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "level": {
            "type": "string",
            "enum": [
              "usually_required",
              "recommended"
            ]
          },
          "description": {
            "type": "string"
          },
          "why": {
            "type": "string"
          },
          "how_on_hypamoon": {
            "type": "string"
          },
          "checked_by_check_readiness": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "level",
          "description",
          "why",
          "how_on_hypamoon",
          "checked_by_check_readiness"
        ]
      }
    },
    "pitfalls": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "pitfall": {
            "type": "string"
          },
          "instead": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "pitfall",
          "instead"
        ]
      }
    },
    "structured_data": {
      "type": "object",
      "properties": {
        "schema_type": {
          "type": "string",
          "description": "The schema.org type, like LocalBusiness, Restaurant, Product or Course."
        },
        "why": {
          "type": "string"
        },
        "snippet": {
          "type": "string",
          "description": "A <script type=\"application/ld+json\"> block with YOUR ... placeholders; fill them with the user's real details only, never invented ones."
        },
        "required": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The fields check_readiness expects in the block."
        }
      },
      "required": [
        "schema_type",
        "why",
        "snippet",
        "required"
      ],
      "description": "Structured data for search engines, ready to fill in and add with deploy_site."
    },
    "note": {
      "type": "string",
      "description": "Guidance, not legal or tax advice."
    },
    "other_types": {
      "type": "object",
      "properties": {
        "available": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "webshop",
              "bookings",
              "restaurant",
              "course_membership",
              "wordpress_portal"
            ]
          }
        },
        "planned": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "available",
        "planned"
      ]
    },
    "known_problems": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "sandbox_blocks_upload",
              "image_too_large",
              "version_conflict",
              "phone_verification_required",
              "site_not_visible",
              "is_hypamoon_down"
            ]
          },
          "symptom": {
            "type": "string",
            "description": "How you recognise it."
          },
          "what_to_do": {
            "type": "string",
            "description": "What you, the agent, do."
          },
          "tell_user": {
            "type": "string",
            "description": "What you can say to the user, in plain words."
          }
        },
        "required": [
          "id",
          "symptom",
          "what_to_do",
          "tell_user"
        ]
      },
      "description": "Known problems (an upload blocked by a sandbox, an image too large, version_conflict, phone verification, a site nobody else can see, is Hypamoon down), each with what to do and what to tell the user. GET /advice?topic=<id> returns one."
    },
    "recipes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "when": {
            "type": "string"
          },
          "event": {
            "type": "string"
          },
          "stop_on": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "day": {
                  "type": "integer"
                },
                "wait_minutes": {
                  "type": "integer"
                },
                "template": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "subject": {
                      "type": "string"
                    },
                    "text": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "name",
                    "subject",
                    "text"
                  ]
                }
              },
              "required": [
                "day",
                "wait_minutes",
                "template"
              ]
            }
          },
          "calls": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "adjust": {
            "type": "string"
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "id",
          "title",
          "when",
          "event",
          "stop_on",
          "variables",
          "steps",
          "calls",
          "adjust",
          "tools"
        ]
      },
      "description": "Recipes to build with existing tools and adjust to the user's words, like dunning for course_membership: reminder emails on subscription.payment_failed on day 1, 4 and 10 with the buyer's signed pay_url. Empty when there are none."
    },
    "summary_markdown": {
      "type": "string"
    }
  },
  "required": [
    "type",
    "title",
    "summary",
    "country",
    "country_source",
    "region",
    "audience",
    "how_to_use",
    "ask_first",
    "build_plan",
    "go_live_checklist",
    "pitfalls",
    "structured_data",
    "note",
    "other_types",
    "known_problems",
    "recipes",
    "summary_markdown"
  ]
}