vocabulary: "1.0.0"

info:
  provider: "Verisk"
  description: "Unified vocabulary for Verisk Insurance Analytics API covering property risk, catastrophe modeling, fire protection classification, risk scoring, and claims benchmarking."
  created: "2026-05-03"
  modified: "2026-05-03"

operational:
  apis:
    - namespace: verisk-insurance-analytics
      version: "1.0"
      baseUrl: https://api.verisk.com/insurance/v1
      status: active

  resources:
    - name: properties
      description: "Property records with risk data and construction attributes"
      apis:
        - verisk-insurance-analytics
      actions:
        - get-property-risk
        - lookup-property-by-address

    - name: risk-scores
      description: "Insurance risk scores for properties, policies, and portfolios"
      apis:
        - verisk-insurance-analytics
      actions:
        - get-risk-scores
        - get-fire-protection-class

    - name: peril-scores
      description: "Catastrophe peril exposure scores for natural hazards"
      apis:
        - verisk-insurance-analytics
      actions:
        - get-peril-scores

    - name: claims-benchmarks
      description: "Industry claims benchmarking metrics by line of business"
      apis:
        - verisk-insurance-analytics
      actions:
        - get-claims-benchmarks

  actions:
    - name: get-property-risk
      method: GET
      pattern: read
      description: "Retrieve property risk assessment"

    - name: lookup-property-by-address
      method: POST
      pattern: query
      description: "Lookup property record by street address"

    - name: get-risk-scores
      method: POST
      pattern: query
      description: "Retrieve risk scores for locations"

    - name: get-fire-protection-class
      method: GET
      pattern: read
      description: "Retrieve ISO Fire Protection Class for a location"

    - name: get-peril-scores
      method: POST
      pattern: query
      description: "Retrieve catastrophe peril scores for locations"

    - name: get-claims-benchmarks
      method: GET
      pattern: read
      description: "Retrieve industry claims benchmarking data"

  schemas:
    core:
      - name: PropertyRisk
        description: "Comprehensive property risk data including construction, fire protection, and peril scores"
      - name: ConstructionData
        description: "Building construction attributes including year built, construction type, and occupancy"
      - name: FireProtectionClass
        description: "ISO Public Protection Classification data for a location"
      - name: Address
        description: "US street address with city, state, zip, and country"
      - name: Coordinates
        description: "Geographic coordinates with latitude and longitude"
    underwriting:
      - name: AddressLookupRequest
        description: "Request to resolve a street address to a property record"
      - name: PropertyLookupResponse
        description: "Property lookup result with match quality and risk data"
      - name: RiskScoreRequest
        description: "Request for risk scores for multiple locations"
      - name: RiskScoreResponse
        description: "Risk scores response by location and score type"
    catastrophe:
      - name: PerilScoreRequest
        description: "Request for catastrophe peril scores for locations"
      - name: PerilScoreResponse
        description: "Catastrophe peril exposure scores by location and peril"
    claims:
      - name: ClaimsBenchmarks
        description: "Industry claims benchmarking metrics for a line of business"

  parameters:
    identifiers:
      - name: propertyId
        description: "Property identifier (address or ISO property ID)"
        type: string
    filters:
      - name: includePerils
        description: "Peril types to include in response"
        type: array
      - name: lineOfBusiness
        description: "Line of insurance business"
        type: string
      - name: state
        description: "US state code (2-letter)"
        type: string
      - name: year
        description: "Data year for benchmarking"
        type: integer
      - name: constructionType
        description: "ISO construction class"
        type: string
      - name: metricType
        description: "Benchmark metric type"
        type: string
    geospatial:
      - name: latitude
        description: "Geographic latitude"
        type: number
      - name: longitude
        description: "Geographic longitude"
        type: number

  enums:
    perils:
      - FIRE
      - WIND
      - HAIL
      - FLOOD
      - EARTHQUAKE
      - WILDFIRE
      - LIGHTNING
      - HURRICANE
      - TORNADO
      - WINTER_STORM
    construction-types:
      - FRAME
      - MASONRY
      - FIRE_RESISTIVE
      - MODIFIED_FIRE_RESISTIVE
      - JOISTED_MASONRY
      - NON_COMBUSTIBLE
    occupancy-types:
      - RESIDENTIAL
      - COMMERCIAL
      - INDUSTRIAL
      - MIXED_USE
    risk-categories:
      - VERY_LOW
      - LOW
      - MODERATE
      - HIGH
      - VERY_HIGH
      - EXTREME
    risk-tiers:
      - TIER_1
      - TIER_2
      - TIER_3
      - TIER_4
      - TIER_5
    score-types:
      - FIRE_PROTECTION_CLASS
      - BUILDING_CODE_EFFECTIVENESS
      - FLOOD_ZONE
      - EARTHQUAKE_ZONE
      - WIND_ZONE
    lines-of-business:
      - HOMEOWNERS
      - AUTO
      - COMMERCIAL_AUTO
      - CGL
      - COMMERCIAL_PROPERTY
      - WORKERS_COMP
    match-quality:
      - EXACT
      - INTERPOLATED
      - ZIP_CENTROID
      - CITY_CENTROID
    metric-types:
      - FREQUENCY
      - SEVERITY
      - COMBINED_RATIO
      - LOSS_RATIO

  authentication:
    schemes:
      - name: BearerAuth
        type: bearer
        description: "JWT bearer token authentication"
      - name: ApiKeyHeader
        type: apikey
        header: X-API-Key
        description: "API key passed in X-API-Key header"

capability:
  workflows:
    - name: insurance-underwriting
      file: capabilities/insurance-underwriting.yaml
      description: "Unified underwriting workflow combining property risk, fire protection classification, catastrophe scoring, and claims benchmarking"
      apis:
        - verisk-insurance-analytics
      tools: 6
      personas:
        - Insurance Underwriter
        - Property Actuary
        - Catastrophe Risk Manager
      domains:
        - Insurance Underwriting
        - Property Risk
        - Catastrophe Modeling
        - Claims Analytics

  personas:
    - id: insurance-underwriter
      name: Insurance Underwriter
      description: "P&C insurance underwriters who evaluate property risk and price policies"
      workflows:
        - insurance-underwriting

    - id: property-actuary
      name: Property Actuary
      description: "Actuaries who model property loss costs and catastrophe exposures"
      workflows:
        - insurance-underwriting

    - id: catastrophe-risk-manager
      name: Catastrophe Risk Manager
      description: "Risk managers overseeing portfolio catastrophe exposure and PML estimates"
      workflows:
        - insurance-underwriting

  domains:
    - name: Insurance Underwriting
      description: "Policy underwriting and risk assessment for P&C insurance"
    - name: Property Risk
      description: "Property-level risk data including construction and hazard scores"
    - name: Catastrophe Modeling
      description: "Natural hazard peril scoring and catastrophe exposure analysis"
    - name: Claims Analytics
      description: "Industry claims benchmarking and loss performance data"

  namespaces:
    consumed:
      - name: verisk-insurance-analytics
        baseUri: https://api.verisk.com/insurance/v1
    rest:
      - name: verisk-underwriting-api
        port: 8080
    mcp:
      - name: verisk-underwriting-mcp
        port: 9080

  binds:
    - name: VERISK_BEARER_TOKEN
      description: "Verisk JWT bearer token for API authentication"
      workflows:
        - insurance-underwriting
    - name: VERISK_API_KEY
      description: "Verisk API key for X-API-Key header authentication"
      workflows:
        - insurance-underwriting

crossReference:
  - resource: properties
    operations:
      - get-property-risk
      - lookup-property-by-address
    workflows:
      - insurance-underwriting
    personas:
      - Insurance Underwriter
      - Property Actuary

  - resource: risk-scores
    operations:
      - get-risk-scores
      - get-fire-protection-class
    workflows:
      - insurance-underwriting
    personas:
      - Insurance Underwriter
      - Property Actuary

  - resource: peril-scores
    operations:
      - get-peril-scores
    workflows:
      - insurance-underwriting
    personas:
      - Catastrophe Risk Manager
      - Property Actuary

  - resource: claims-benchmarks
    operations:
      - get-claims-benchmarks
    workflows:
      - insurance-underwriting
    personas:
      - Insurance Underwriter
      - Property Actuary