{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/andrewsfreebies-com/json-schema/andrewsfreebies-com-entitlement-schema.json",
  "title": "Entitlement",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/andrewsfreebies-com-openapi.json#/components/schemas/Entitlement",
  "type": "object",
  "required": [
    "id",
    "name",
    "provider",
    "entitlement_type",
    "entitlement_type_label",
    "entitlement_type_context",
    "benefit",
    "discovery",
    "access",
    "status",
    "source",
    "taxonomy",
    "verification_readiness",
    "action_url",
    "official_action"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "provider": {
      "type": "string"
    },
    "entitlement_type": {
      "type": "string",
      "enum": [
        "bank-account-bonus",
        "benefit-tracker",
        "benefits-counseling",
        "business-support",
        "card-linked-offer",
        "community-benefit",
        "community-program",
        "consumer-complaint",
        "credit-card-welcome-bonus",
        "cultural-access",
        "customer-loyalty-perk",
        "deal-directory",
        "education-program",
        "eligibility-directory",
        "employment-program",
        "family-support",
        "free-admission",
        "government-benefit",
        "grant",
        "health-coverage",
        "health-locator",
        "hotline",
        "housing-assistance",
        "insurance-benefit",
        "library-access",
        "library-benefit",
        "public-resource",
        "rebate",
        "rights-advocacy",
        "rights-enforcement",
        "school-program",
        "shopping-portal",
        "tax-credit"
      ],
      "description": "Primary record archetype; this value does not establish price or individual eligibility."
    },
    "entitlement_type_label": {
      "type": "string"
    },
    "entitlement_type_context": {
      "type": "object",
      "properties": {
        "definition": {
          "type": "string"
        },
        "domain": {
          "type": "string"
        },
        "archetype": {
          "type": "string"
        },
        "agent_instruction": {
          "type": "string"
        }
      }
    },
    "summary": {
      "type": "string"
    },
    "benefit": {
      "type": "object",
      "properties": {
        "description": {
          "type": "string"
        },
        "estimated_value_usd": {
          "type": [
            "number",
            "null"
          ]
        }
      }
    },
    "discovery": {
      "type": "object",
      "properties": {
        "focus": {
          "type": "string",
          "enum": [
            "redeemable-value",
            "public-service"
          ]
        },
        "has_estimated_dollar_value": {
          "type": "boolean"
        }
      }
    },
    "access": {
      "type": "object",
      "properties": {
        "relationships": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "requirements": {
          "type": "string"
        },
        "activation": {
          "type": "string"
        },
        "cost_basis": {
          "type": "string",
          "enum": [
            "no-cost",
            "no-additional-cost",
            "discounted",
            "subsidized",
            "requires-purchase",
            "requires-spend",
            "requires-deposit",
            "paid-membership",
            "varies"
          ],
          "description": "Normalized financial condition; read cost_basis_context and fees before describing the benefit as free."
        },
        "cost_basis_label": {
          "type": "string"
        },
        "cost_basis_context": {
          "type": "object",
          "properties": {
            "classification": {
              "type": "string"
            },
            "definition": {
              "type": "string"
            },
            "agent_instruction": {
              "type": "string"
            },
            "variation_patterns": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string"
              }
            },
            "does_not_mean": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string"
              }
            }
          }
        },
        "fees": {
          "type": "string"
        },
        "personalized": {
          "type": "boolean"
        },
        "regions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "expires": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "parent": {
      "type": [
        "object",
        "null"
      ],
      "description": "Parent entitlement when this record exposes one independently searchable benefit from a broader access relationship.",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "relationship": {
          "type": "string",
          "enum": [
            "benefit-of"
          ]
        },
        "web_url": {
          "type": "string"
        }
      }
    },
    "coverage": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "level": {
          "type": "string",
          "enum": [
            "national",
            "state",
            "local"
          ]
        },
        "family": {
          "type": "string"
        },
        "jurisdiction": {
          "type": "string"
        },
        "maturity": {
          "type": "string",
          "enum": [
            "locator",
            "direct"
          ]
        }
      }
    },
    "status": {
      "type": "string"
    },
    "last_checked": {
      "type": "string",
      "format": "date"
    },
    "verification_readiness": {
      "$ref": "#/$defs/VerificationReadiness"
    },
    "action_url": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri",
      "description": "Measured official-action path; null means the record is inspectable but must not be recommended for action."
    },
    "official_action": {
      "$ref": "#/$defs/OfficialActionState"
    },
    "claim_url": {
      "type": "string",
      "format": "uri"
    },
    "source_url": {
      "type": "string",
      "format": "uri"
    },
    "source": {
      "type": "object"
    },
    "taxonomy": {
      "type": "object",
      "properties": {
        "version": {
          "type": "string"
        },
        "url": {
          "type": "string"
        }
      }
    }
  },
  "$defs": {
    "OfficialActionState": {
      "type": "object",
      "required": [
        "allowed",
        "status",
        "reason"
      ],
      "properties": {
        "allowed": {
          "type": "boolean"
        },
        "status": {
          "type": "string",
          "enum": [
            "ready",
            "source-navigation",
            "withheld"
          ]
        },
        "reason": {
          "type": "string",
          "description": "Instruction for whether an agent may recommend the official action path."
        }
      }
    },
    "VerificationOutcome": {
      "type": "string",
      "enum": [
        "confirmed-exact",
        "confirmed-partial",
        "terms-changed",
        "explicitly-expired",
        "moved",
        "blocked",
        "fetch-error",
        "not-found",
        "unknown"
      ],
      "description": "Conservative field-level audit result. blocked, fetch-error, not-found, and unknown do not establish expiration."
    },
    "VerificationReadiness": {
      "type": "object",
      "required": [
        "status",
        "latest_outcome",
        "latest_checked_at",
        "interpretation"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "audit-confirmed-exact",
            "audit-confirmed-partial",
            "audit-inconclusive",
            "audit-warning",
            "not-audited"
          ]
        },
        "latest_outcome": {
          "oneOf": [
            {
              "$ref": "#/$defs/VerificationOutcome"
            },
            {
              "type": "null"
            }
          ]
        },
        "latest_checked_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "interpretation": {
          "type": "string",
          "description": "Factual guidance for using the latest audit without treating an inconclusive fetch as expiration."
        }
      }
    }
  }
}