modules/bandi-agevolazioni/schemas/opportunity_handoff.schema.json

15.9 KB · Oct 2, 2026 · 00:29 UTC
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://mparanza.com/schemas/bandi-agevolazioni/opportunity-handoff-3.0.json",
  "title": "Reviewed and self-verifiable opportunity handoff",
  "type": "object",
  "additionalProperties": false,
  "required": ["schema_version", "plugin", "radar_id", "radar_revision", "created_at", "client_ref", "profile", "profile_evidence", "source_plan_entries", "opportunity", "match", "coverage", "source_entries_sha256", "selection_sha256", "limitations"],
  "properties": {
    "schema_version": {"const": "3.0"},
    "plugin": {"const": "bandi-agevolazioni"},
    "radar_id": {"$ref": "#/$defs/id"},
    "radar_revision": {"type": "integer", "minimum": 0},
    "created_at": {"type": "string", "format": "date-time"},
    "client_ref": {"$ref": "#/$defs/id"},
    "profile": {"$ref": "#/$defs/profile"},
    "profile_evidence": {"type": "array", "items": {"$ref": "#/$defs/profileEvidence"}},
    "source_plan_entries": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/sourcePlanEntry"}},
    "opportunity": {"$ref": "#/$defs/opportunity"},
    "match": {"$ref": "#/$defs/match"},
    "coverage": {"$ref": "#/$defs/coverage"},
    "source_entries_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
    "selection_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
    "limitations": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}
  },
  "$defs": {
    "id": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$"},
    "idList": {"type": "array", "uniqueItems": true, "items": {"$ref": "#/$defs/id"}},
    "decimal": {"type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"},
    "reviewStatus": {"enum": ["proposed", "confirmed", "rejected", "blocked"]},
    "contribution": {
      "type": "object",
      "additionalProperties": false,
      "required": ["origin", "provider", "model", "prompt_template_version", "recorded_by", "recorded_at"],
      "properties": {
        "origin": {"enum": ["model_suggested", "user_supplied", "document_observation", "mechanical_observation"]},
        "provider": {"type": "string", "minLength": 1},
        "model": {"type": "string", "minLength": 1},
        "prompt_template_version": {"type": "string", "minLength": 1},
        "recorded_by": {"$ref": "#/$defs/id"},
        "recorded_at": {"type": "string", "format": "date-time"},
        "model_session_ref": {
          "oneOf": [{"$ref": "#/$defs/id"}, {"type": "null"}]
        },
        "session_assurance": {
          "enum": ["operator_asserted_not_provider_authenticated", "not_applicable"]
        }
      }
    },
    "revisionEvent": {
      "type": "object",
      "additionalProperties": false,
      "required": ["revision_id", "observed_at", "rationale", "evidence_refs", "source_ids", "changed_fields", "previous_sha256", "review_status"],
      "properties": {
        "revision_id": {"$ref": "#/$defs/id"},
        "observed_at": {"type": "string", "format": "date-time"},
        "rationale": {"type": "string", "minLength": 1},
        "evidence_refs": {"$ref": "#/$defs/idList"},
        "source_ids": {"$ref": "#/$defs/idList"},
        "changed_fields": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "minLength": 1}},
        "previous_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
        "review_status": {"const": "confirmed"}
      }
    },
    "facet": {
      "type": "object",
      "additionalProperties": false,
      "required": ["facet_id", "category", "value", "as_of_date", "evidence_refs", "provenance", "review_status"],
      "properties": {
        "facet_id": {"$ref": "#/$defs/id"},
        "category": {"enum": ["territory", "ateco", "size", "legal_form", "company_age", "ownership", "planned_investment", "property", "workforce", "energy", "digitization", "vehicles", "export", "training", "innovation", "other"]},
        "value": {"type": "string", "minLength": 1},
        "as_of_date": {"type": "string", "format": "date"},
        "evidence_refs": {"$ref": "#/$defs/idList"},
        "provenance": {"enum": ["document_observation", "user_assertion", "model_inference"]},
        "review_status": {"const": "confirmed"}
      }
    },
    "profile": {
      "type": "object",
      "additionalProperties": false,
      "required": ["client_ref", "revision", "revision_history", "facets", "review_status", "contribution"],
      "properties": {
        "client_ref": {"$ref": "#/$defs/id"},
        "revision": {"type": "integer", "minimum": 1},
        "revision_history": {"type": "array", "items": {"$ref": "#/$defs/revisionEvent"}},
        "facets": {"type": "array", "items": {"$ref": "#/$defs/facet"}},
        "review_status": {"const": "confirmed"},
        "contribution": {"$ref": "#/$defs/contribution"}
      }
    },
    "profileEvidence": {
      "type": "object",
      "additionalProperties": false,
      "required": ["evidence_id", "client_ref", "evidence_kind", "receipt_ref", "sha256", "as_of_date", "description", "review_status", "contribution"],
      "properties": {
        "evidence_id": {"$ref": "#/$defs/id"},
        "client_ref": {"$ref": "#/$defs/id"},
        "evidence_kind": {"enum": ["document_receipt", "professional_assertion", "other_receipt"]},
        "receipt_ref": {"$ref": "#/$defs/id"},
        "sha256": {"type": ["string", "null"], "pattern": "^[a-f0-9]{64}$"},
        "as_of_date": {"type": "string", "format": "date"},
        "description": {"type": "string", "minLength": 1},
        "review_status": {"const": "confirmed"},
        "contribution": {"$ref": "#/$defs/contribution"}
      }
    },
    "sourcePlanEntry": {
      "type": "object",
      "additionalProperties": false,
      "required": ["source_id", "authority_level", "publisher", "official_url", "discovery_role", "source_surface", "territories", "categories", "act_families", "relevance_rationale", "profile_refs", "check_id", "last_scan_id", "check_status", "checked_at", "window_start", "window_end", "next_check_on", "result_count", "error_code", "cursor_before", "cursor_after", "review_status", "check_review_status", "contribution"],
      "properties": {
        "source_id": {"$ref": "#/$defs/id"},
        "authority_level": {"enum": ["national", "regional", "regional_agency", "chamber", "municipality", "province", "eu", "sectoral", "other"]},
        "publisher": {"type": "string", "minLength": 1},
        "official_url": {"type": "string", "format": "uri", "pattern": "^https://"},
        "discovery_role": {"enum": ["priority_direct", "supplemental_direct"]},
        "source_surface": {"enum": ["official_register", "official_gazette", "act_repository", "funding_portal", "publisher_page", "other_official"]},
        "territories": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "minLength": 1}},
        "categories": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "minLength": 1}},
        "act_families": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"enum": ["call", "gu_issue", "ministerial_decree", "programming_decree", "dgr", "ddr", "bur_issue", "annex", "faq", "amendment", "portal_notice", "other"]}},
        "relevance_rationale": {"type": "string", "minLength": 1},
        "profile_refs": {"$ref": "#/$defs/idList"},
        "check_id": {"$ref": "#/$defs/id"},
        "last_scan_id": {"$ref": "#/$defs/id"},
        "check_status": {"const": "checked"},
        "checked_at": {"type": "string", "format": "date-time"},
        "window_start": {"type": "string", "format": "date"},
        "window_end": {"type": "string", "format": "date"},
        "next_check_on": {"type": ["string", "null"], "format": "date"},
        "result_count": {"type": "integer", "minimum": 0},
        "error_code": {"type": "null"},
        "issue_inventory": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/issueInventory"}]},
        "cursor_before": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/sourceCursor"}]},
        "cursor_after": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/sourceCursor"}]},
        "review_status": {"const": "confirmed"},
        "check_review_status": {"const": "confirmed"},
        "contribution": {"$ref": "#/$defs/contribution"}
      }
    },
    "gazetteIssue": {"type": "object", "additionalProperties": false, "required": ["issue_id", "official_url", "publication_date", "status", "checked_at", "act_urls", "notes"], "properties": {"issue_id": {"$ref": "#/$defs/id"}, "official_url": {"type": "string", "format": "uri", "pattern": "^https://"}, "publication_date": {"type": "string", "format": "date"}, "status": {"enum": ["checked", "unavailable", "failed", "not_checked"]}, "checked_at": {"type": ["string", "null"], "format": "date-time"}, "act_urls": {"type": "array", "uniqueItems": true, "items": {"type": "string", "format": "uri", "pattern": "^https://"}}, "notes": {"type": "string", "minLength": 1}}, "allOf": [{"if": {"properties": {"status": {"const": "checked"}}}, "then": {"properties": {"checked_at": {"type": "string", "format": "date-time"}}}}]},
    "issueInventory": {"type": "object", "additionalProperties": false, "required": ["index_urls", "enumerated_at", "window_start", "window_end", "enumeration_complete", "empty_window_rationale", "issues"], "properties": {"index_urls": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "format": "uri", "pattern": "^https://"}}, "enumerated_at": {"type": "string", "format": "date-time"}, "window_start": {"type": "string", "format": "date"}, "window_end": {"type": "string", "format": "date"}, "enumeration_complete": {"type": "boolean"}, "empty_window_rationale": {"type": "string"}, "issues": {"type": "array", "items": {"$ref": "#/$defs/gazetteIssue"}}}},
    "sourceCursor": {
      "type": "object",
      "additionalProperties": false,
      "required": ["external_id", "publication_date", "official_url", "recorded_at"],
      "anyOf": [
        {"properties": {"external_id": {"type": "string", "minLength": 1}}},
        {"properties": {"publication_date": {"type": "string", "format": "date"}}},
        {"properties": {"official_url": {"type": "string", "format": "uri", "pattern": "^https://"}}}
      ],
      "properties": {
        "external_id": {"type": ["string", "null"], "minLength": 1},
        "publication_date": {"type": ["string", "null"], "format": "date"},
        "official_url": {"type": ["string", "null"], "format": "uri", "pattern": "^https://"},
        "recorded_at": {"type": "string", "format": "date-time"}
      }
    },
    "coverage": {
      "type": "object",
      "additionalProperties": false,
      "required": ["plan_entry_count", "planned_count", "completed_count", "unavailable_count", "failed_count", "unreviewed_count", "rejected_count", "check_review_pending_count", "ratio_basis_points", "status", "statement"],
      "properties": {
        "plan_entry_count": {"type": "integer", "minimum": 1},
        "planned_count": {"type": "integer", "minimum": 1},
        "completed_count": {"type": "integer", "minimum": 1},
        "unavailable_count": {"type": "integer", "minimum": 0},
        "failed_count": {"type": "integer", "minimum": 0},
        "unreviewed_count": {"const": 0},
        "rejected_count": {"const": 0},
        "check_review_pending_count": {"const": 0},
        "ratio_basis_points": {"const": 10000},
        "status": {"const": "planned_sources_checked"},
        "statement": {"type": "string", "minLength": 1}
      }
    },
    "lifecycleObservation": {
      "type": "object",
      "additionalProperties": false,
      "required": ["observation_id", "status", "effective_date", "observed_at", "source_ids", "rationale", "review_status"],
      "properties": {
        "observation_id": {"$ref": "#/$defs/id"},
        "status": {"enum": ["announced", "programmed", "no_operating_calendar", "approved", "published", "upcoming", "open", "closing_soon", "extended", "modified", "funds_available", "suspended", "closed", "refinanced", "unknown"]},
        "effective_date": {"type": ["string", "null"], "format": "date"},
        "observed_at": {"type": "string", "format": "date-time"},
        "source_ids": {"$ref": "#/$defs/idList"},
        "rationale": {"type": "string", "minLength": 1},
        "review_status": {"const": "confirmed"}
      }
    },
    "opportunity": {
      "type": "object",
      "additionalProperties": false,
      "required": ["opportunity_id", "revision", "revision_history", "official_title", "issuer", "official_url", "source_ids", "opening_date", "closing_date", "summary", "lifecycle_history", "current_lifecycle", "review_status", "contribution"],
      "properties": {
        "opportunity_id": {"$ref": "#/$defs/id"},
        "revision": {"type": "integer", "minimum": 1},
        "revision_history": {"type": "array", "items": {"$ref": "#/$defs/revisionEvent"}},
        "official_title": {"type": "string", "minLength": 1},
        "issuer": {"type": "string", "minLength": 1},
        "official_url": {"type": "string", "format": "uri", "pattern": "^https://"},
        "source_ids": {"$ref": "#/$defs/idList"},
        "opening_date": {"type": ["string", "null"], "format": "date"},
        "closing_date": {"type": ["string", "null"], "format": "date"},
        "summary": {"type": "string", "minLength": 1},
        "lifecycle_history": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/lifecycleObservation"}},
        "current_lifecycle": {"enum": ["announced", "programmed", "no_operating_calendar", "approved", "published", "upcoming", "open", "closing_soon", "extended", "modified", "funds_available", "suspended", "closed", "refinanced", "unknown"]},
        "review_status": {"const": "confirmed"},
        "contribution": {"$ref": "#/$defs/contribution"}
      }
    },
    "economicEstimate": {
      "type": "object",
      "additionalProperties": false,
      "required": ["currency", "gross_benefit_min", "gross_benefit_max", "preparation_cost_min", "preparation_cost_max", "net_value_min", "net_value_max", "methodology", "assumptions", "review_status"],
      "properties": {
        "currency": {"type": "string", "pattern": "^[A-Z]{3}$"},
        "gross_benefit_min": {"$ref": "#/$defs/decimal"},
        "gross_benefit_max": {"$ref": "#/$defs/decimal"},
        "preparation_cost_min": {"$ref": "#/$defs/decimal"},
        "preparation_cost_max": {"$ref": "#/$defs/decimal"},
        "net_value_min": {"$ref": "#/$defs/decimal"},
        "net_value_max": {"$ref": "#/$defs/decimal"},
        "methodology": {"const": "gross_benefit_range_minus_preparation_cost_range"},
        "assumptions": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
        "review_status": {"const": "confirmed"}
      }
    },
    "match": {
      "type": "object",
      "additionalProperties": false,
      "required": ["match_id", "opportunity_id", "client_ref", "compatibility", "rationale", "profile_facet_ids", "source_ids", "missing_information", "contradictions", "application_complexity", "economic_estimate", "recommended_action", "review_status", "contribution"],
      "properties": {
        "match_id": {"$ref": "#/$defs/id"},
        "opportunity_id": {"$ref": "#/$defs/id"},
        "client_ref": {"$ref": "#/$defs/id"},
        "compatibility": {"enum": ["high", "medium", "low", "no_match", "unknown"]},
        "rationale": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
        "profile_facet_ids": {"$ref": "#/$defs/idList"},
        "source_ids": {"$ref": "#/$defs/idList"},
        "missing_information": {"type": "array", "items": {"type": "string", "minLength": 1}},
        "contradictions": {"type": "array", "items": {"type": "string", "minLength": 1}},
        "application_complexity": {"enum": ["simple", "moderate", "complex", "unknown"]},
        "economic_estimate": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/economicEstimate"}]},
        "recommended_action": {"enum": ["contact_client", "monitor", "deprioritize", "do_not_pursue", "professional_review"]},
        "review_status": {"const": "confirmed"},
        "contribution": {"$ref": "#/$defs/contribution"}
      }
    }
  }
}
SHA-256: 4f071e9f53bc08ad25cf90339096e1a8243666c4099fd70d80574d6b1b0a70f8