# CallForApplication Class
# Models funding calls and grant application opportunities from heritage funding organisations
#
# Created November 2025 to link:
# - EncompassingBody (FundingOrganisation subclass) → issues → CallForApplication[]
# - Custodians can apply to these calls for heritage project funding
#
# Key relationships:
#   FundingOrganisation (EncompassingBody) --issues--> CallForApplication
#   CallForApplication --funding_organisation--> FundingOrganisation
#   CallForApplication --web_observations--> WebObservation[] (provenance)
#
# Examples:
#   - Horizon Europe CL2 2025 Cultural Heritage calls
#   - Creative Europe Cooperation Projects 2025
#   - European Heritage Awards 2026 nominations
#   - National Lottery Heritage Fund UK grants

id: https://nde.nl/ontology/hc/class/CallForApplication
name: CallForApplication
title: CallForApplication Class

prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  schema: http://schema.org/
  dcterms: http://purl.org/dc/terms/
  foaf: http://xmlns.com/foaf/0.1/
  prov: http://www.w3.org/ns/prov#
  org: http://www.w3.org/ns/org#
  skos: http://www.w3.org/2004/02/skos/core#

imports:
  - linkml:types
  - ../enums/CallForApplicationStatusEnum
  - ../enums/FundingRequirementTypeEnum
  - ./FundingRequirement
  - ../slots/contact_email
  - ../slots/keywords

default_prefix: hc

slots:
  call_id:
    identifier: true
    range: uriorcurie
    description: Unique identifier for this funding call
  
  call_title:
    range: string
    description: Official title of the funding call
  
  call_short_name:
    range: string
    description: Short name or code for the call (e.g., "CL2-2025-HERITAGE-01")
  
  call_description:
    range: string
    description: Detailed description of the funding call and its objectives
  
  call_status:
    range: CallForApplicationStatusEnum
    description: Current lifecycle status of the funding call
  
  call_url:
    range: uri
    description: Official call documentation or application portal URL
  
  application_opening_date:
    range: date
    description: Date when application submissions open
  
  application_deadline:
    range: date
    description: Final deadline for application submissions
  
  results_expected_date:
    range: date
    description: Expected date for announcement of funding decisions
  
  total_budget:
    range: string
    description: Total funding budget available for this call (with currency)
  
  typical_grant_range:
    range: string
    description: Typical grant amount range per project (e.g., "€100K-€500K")
  
  eligible_applicants:
    range: string
    multivalued: true
    description: Types of organisations eligible to apply
  
  eligible_countries:
    range: string
    multivalued: true
    description: Countries whose organisations can apply
  
  thematic_areas:
    range: string
    multivalued: true
    description: Thematic focus areas or topics covered by the call
  
  heritage_types:
    range: string
    multivalued: true
    description: Types of heritage addressed (tangible, intangible, digital, etc.)
  
  funding_rate:
    range: string
    description: Maximum funding rate (e.g., "80% of eligible costs")
  
  co_funding_required:
    range: boolean
    description: Whether co-funding/match funding is required
  
  partnership_required:
    range: boolean
    description: Whether consortium/partnership is required for application
  
  minimum_partners:
    range: integer
    description: Minimum number of partners required (if partnership required)
  
  issuing_organisation:
    range: uriorcurie
    description: FundingOrganisation that issues this call
  
  parent_programme:
    range: string
    description: Parent funding programme (e.g., "Horizon Europe", "Creative Europe")
  
  programme_year:
    range: integer
    description: Programme year or funding cycle
  
  call_identifiers:
    range: uriorcurie
    multivalued: true
    description: External identifiers (EU Funding & Tenders ID, etc.)
  
  related_calls:
    range: uriorcurie
    multivalued: true
    description: Related or predecessor/successor calls
  
  # NOTE: contact_email imported from global slot ../slots/contact_email.yaml
  
  info_session_dates:
    range: string
    multivalued: true
    description: Dates of information sessions or webinars about the call
  
  # NOTE: keywords imported from global slot ../slots/keywords.yaml
  
  web_observations:
    range: uriorcurie
    multivalued: true
    description: WebObservation records documenting provenance of call information
  
  requirements:
    range: FundingRequirement
    multivalued: true
    inlined: true
    inlined_as_list: true
    description: |
      Structured requirements for this funding call, each linked to provenance.
      Replaces unstructured eligibility fields with typed, trackable requirements.
  
  funded_projects:
    range: uriorcurie
    multivalued: true
    description: |
      Projects that received funding through this call.
      Inverse of Project.funding_call.

classes:
  CallForApplication:
    class_uri: schema:Offer
    description: |
      A funding call or grant application opportunity issued by a heritage funding
      organisation, inviting heritage custodians to apply for project funding.
      
      **PURPOSE**:
      
      CallForApplication bridges the gap between:
      - **FundingOrganisation** (entities that provide heritage funding)
      - **Heritage Custodians** (institutions seeking funding for projects)
      
      Funding organisations like the European Commission, national heritage funds,
      and private foundations issue regular calls for applications. These calls have
      defined timeframes, budgets, eligibility criteria, and thematic focus areas.
      
      **KEY RELATIONSHIPS**:
      
      ```
      FundingOrganisation (e.g., European Commission)
            │
            ├── issues ──→ CallForApplication (e.g., "CL2-2025-HERITAGE-01")
            │                     │
            │                     ├── web_observations ──→ WebObservation[]
            │                     │                        (provenance tracking)
            │                     │
            │                     └── funded_projects ──→ Project[]
            │                                              │
            │                                              └── funding_call (inverse)
            │
            └── parent_programme: "Horizon Europe"
      ```
      
      **LIFECYCLE TRACKING**:
      
      Calls progress through defined stages tracked via `call_status`:
      - ANNOUNCED → OPEN → CLOSING_SOON → CLOSED → UNDER_REVIEW → RESULTS_PUBLISHED
      - May be CANCELLED or REOPENED under special circumstances
      
      **PROVENANCE TRACKING**:
      
      Because call information is often extracted from web sources, each
      CallForApplication should link to one or more WebObservation records
      documenting when and where the information was retrieved.
      
      **ONTOLOGY ALIGNMENT**:
      
      - **Schema.org**: `schema:Offer` - "An offer to transfer some rights to an item
        or to provide a service" (funding is a service/offer to heritage institutions)
      - **Schema.org**: `schema:Grant` - Related class for awarded grants
      - **Schema.org**: `schema:MonetaryGrant` - For actual grant awards
      - **PROV-O**: `prov:Activity` - Call issuance as activity
      - **Dublin Core**: `dcterms:relation` for related calls
      
      **EXAMPLES**:
      
      1. **Horizon Europe CL2 2025 Heritage Calls**
         - issuing_organisation: European Commission
         - parent_programme: Horizon Europe
         - total_budget: €82.5M
         - application_deadline: 2025-09-16
         - thematic_areas: Cultural heritage preservation, digital heritage
         
      2. **Creative Europe Cooperation Projects 2025**
         - issuing_organisation: EACEA (European Education and Culture Executive Agency)
         - parent_programme: Creative Europe
         - partnership_required: true
         - minimum_partners: 3 (from different EU countries)
         
      3. **National Lottery Heritage Fund UK**
         - issuing_organisation: National Lottery Heritage Fund
         - typical_grant_range: £10K-£10M
         - eligible_countries: [UK, Northern Ireland, Scotland, Wales]
         
      4. **European Heritage Awards 2026**
         - issuing_organisation: Europa Nostra
         - call_type: Awards/Recognition (not direct funding)
         - thematic_areas: Research, Conservation, Education, Engagement
    
    exact_mappings:
      - schema:Offer
    
    close_mappings:
      - schema:Grant
      - schema:MonetaryGrant
      - schema:FundingScheme
      - prov:Activity
    
    related_mappings:
      - org:Organization
      - schema:Action
      - dcterms:BibliographicResource
    
    slots:
      - call_id
      - call_title
      - call_short_name
      - call_description
      - call_status
      - call_url
      - application_opening_date
      - application_deadline
      - results_expected_date
      - total_budget
      - typical_grant_range
      - eligible_applicants
      - eligible_countries
      - thematic_areas
      - heritage_types
      - funding_rate
      - co_funding_required
      - partnership_required
      - minimum_partners
      - issuing_organisation
      - parent_programme
      - programme_year
      - call_identifiers
      - related_calls
      - contact_email
      - info_session_dates
      - keywords
      - web_observations
      - requirements
      - funded_projects
    
    slot_usage:
      call_id:
        identifier: true
        required: true
        range: uriorcurie
        description: |
          Unique identifier for this funding call.
          Format: https://nde.nl/ontology/hc/call/{issuing-org-slug}/{call-code}
        pattern: "^https://nde\\.nl/ontology/hc/call/[a-z0-9-]+/[a-z0-9-]+$"
        examples:
          - value: "https://nde.nl/ontology/hc/call/ec/cl2-2025-heritage-01"
            description: "Horizon Europe CL2 heritage call"
          - value: "https://nde.nl/ontology/hc/call/nlhf/medium-grants-2025"
            description: "National Lottery Heritage Fund medium grants"
      
      call_title:
        slot_uri: skos:prefLabel
        required: true
        range: string
        description: |
          Official title of the funding call.
          Should match documentation exactly for discoverability.
        examples:
          - value: "Cultural heritage, cultural and creative industries"
            description: "Horizon Europe Cluster 2 call title"
          - value: "European Cooperation Projects"
            description: "Creative Europe call title"
      
      call_short_name:
        slot_uri: skos:altLabel
        range: string
        description: |
          Short name or official code for the call.
          Often used in EU Funding & Tenders portal.
        examples:
          - value: "CL2-2025-HERITAGE-01"
            description: "Horizon Europe call code"
          - value: "CREA-CULT-2025-COOP"
            description: "Creative Europe cooperation call code"
      
      call_status:
        required: true
        range: CallForApplicationStatusEnum
        description: |
          Current lifecycle status of the funding call.
          
          See CallForApplicationStatusEnum for status values:
          - ANNOUNCED: Call published, not yet open
          - OPEN: Currently accepting applications
          - CLOSING_SOON: < 30 days until deadline
          - CLOSED: Deadline passed
          - UNDER_REVIEW: Evaluation in progress
          - RESULTS_PUBLISHED: Decisions announced
          - CANCELLED: Call terminated
          - REOPENED: Previously closed call reactivated
        examples:
          - value: "OPEN"
            description: "Currently accepting applications"
          - value: "CLOSING_SOON"
            description: "Deadline approaching"
      
      application_deadline:
        slot_uri: schema:validThrough
        required: true
        range: date
        description: |
          Final deadline for application submissions.
          Critical field for heritage custodians planning applications.
        examples:
          - value: "2025-09-16"
            description: "Horizon Europe CL2 2025 deadline"
      
      total_budget:
        slot_uri: schema:price
        range: string
        description: |
          Total funding budget available for this call including currency.
          Format: "{amount} {currency}" e.g., "82.5M EUR"
        examples:
          - value: "82.5M EUR"
            description: "Horizon Europe heritage budget"
          - value: "500M GBP"
            description: "National Lottery Heritage Fund annual budget"
      
      eligible_applicants:
        range: string
        multivalued: true
        inlined_as_list: true
        description: |
          Types of organisations eligible to apply for this call.
          Important for heritage custodians to determine eligibility.
        examples:
          - value: "Public bodies"
          - value: "Non-profit organisations"
          - value: "Research institutions"
          - value: "SMEs"
          - value: "Higher education institutions"
          - value: "Cultural heritage institutions"
      
      issuing_organisation:
        slot_uri: schema:offeredBy
        required: true
        range: uriorcurie
        description: |
          The FundingOrganisation that issues this call.
          
          URI reference to EncompassingBody entity (FundingOrganisation subclass).
          Format: https://nde.nl/ontology/hc/encompassing-body/funding/{slug}
          
          **Inverse of FundingOrganisation.issued_calls**:
          - FundingOrganisation → issued_calls → CallForApplication[]
          - CallForApplication → issuing_organisation → FundingOrganisation
        examples:
          - value: "https://nde.nl/ontology/hc/encompassing-body/funding/ec-rea"
            description: "European Research Executive Agency"
          - value: "https://nde.nl/ontology/hc/encompassing-body/funding/nlhf"
            description: "National Lottery Heritage Fund"
      
      web_observations:
        slot_uri: prov:wasInfluencedBy
        range: uriorcurie
        multivalued: true
        inlined_as_list: true
        description: |
          WebObservation records documenting the provenance of call information.
          
          Because call details are often extracted from web sources (EU portals,
          funding organisation websites, etc.), this field links to WebObservation
          records that track when and where information was retrieved.
          
          **PROV-O Integration**:
          - CallForApplication prov:wasInfluencedBy WebObservation
          - WebObservation prov:used SourceDocument (the web page)
          - WebObservation pav:retrievedOn datetime
        examples:
          - value: "https://nde.nl/ontology/hc/observation/web/2025-11-29/eu-horizon-cl2"
            description: "Web observation of Horizon Europe call page"
      
      requirements:
        slot_uri: dcterms:requires
        range: FundingRequirement
        multivalued: true
        inlined: true
        inlined_as_list: true
        description: |
          Structured requirements for this funding call with provenance tracking.
          
          Each FundingRequirement represents a single eligibility criterion,
          financial condition, partnership requirement, or other constraint.
          Requirements link to WebObservation for source tracking.
          
          **REPLACES UNSTRUCTURED FIELDS**:
          
          The `requirements` slot provides structured alternatives to:
          - `eligible_applicants` → ELIGIBILITY_ORGANIZATIONAL requirements
          - `eligible_countries` → ELIGIBILITY_GEOGRAPHIC requirements
          - `funding_rate` → FINANCIAL_RATE requirements
          - `co_funding_required` → FINANCIAL_COFUNDING requirements
          - `partnership_required` → PARTNERSHIP_* requirements
          - `minimum_partners` → PARTNERSHIP_MINIMUM_PARTNERS requirements
          
          Original fields are retained for backward compatibility but
          `requirements` provides richer, provenance-tracked alternatives.
          
          **PROVENANCE CHAIN**:
          
          ```
          CallForApplication
                │
                └── requirements ──→ FundingRequirement[]
                                          │
                                          ├── requirement_type: ELIGIBILITY_*
                                          ├── requirement_text: "..."
                                          ├── requirement_value: "..."
                                          │
                                          └── observed_in ──→ WebObservation
                                                                  │
                                                                  └── source_url, retrieved_on, ...
          ```
          
          **EXAMPLE USAGE**:
          
          ```yaml
          requirements:
            - requirement_id: ".../min-partners-3"
              requirement_type: PARTNERSHIP_MINIMUM_PARTNERS
              requirement_text: "Minimum 3 partners from 3 EU countries"
              requirement_value: "3"
              requirement_unit: "partners"
              is_mandatory: true
              observed_in: ".../observation/web/2025-11-29/eu-horizon"
              extraction_confidence: 0.98
            
            - requirement_id: ".../open-access"
              requirement_type: TECHNICAL_OPEN_ACCESS
              requirement_text: "Immediate open access required"
              requirement_value: "immediate"
              is_mandatory: true
              observed_in: ".../observation/web/2025-11-29/eu-horizon"
          ```
        examples:
          - value: "See FundingRequirement class examples"
            description: "Structured requirements with provenance"
      
      funded_projects:
        slot_uri: schema:fundedItem
        range: uriorcurie
        multivalued: true
        inlined_as_list: true
        description: |
          Projects that received funding through this call.
          
          URI references to Project entities.
          Format: https://nde.nl/ontology/hc/project/{organizing-body-slug}/{project-slug}
          
          **Inverse of Project.funding_call**:
          - CallForApplication → funded_projects → Project[]
          - Project → funding_call → CallForApplication
          
          **Schema.org Alignment**:
          Uses `schema:fundedItem` - "Indicates something directly or indirectly 
          funded or co-funded through a Grant." Since CallForApplication represents
          a funding opportunity that results in grants, the funded projects are
          the items ultimately funded.
          
          **RELATIONSHIP MODEL**:
          
          ```
          CallForApplication (e.g., "HORIZON-CL2-2025-HERITAGE-01")
                │
                └── funded_projects ──→ Project[]
                                          │
                                          └── funding_call ──→ CallForApplication
          ```
          
          **DISTINCTION FROM funding_source**:
          
          - `Project.funding_source`: String description of where funding comes from
            (legacy field, may list multiple sources including non-call sources)
          - `Project.funding_call`: URI reference to specific CallForApplication
            that funded this project (structured, semantic link)
          
          Both can coexist - funding_source for human readability, funding_call
          for machine-navigable linked data.
        examples:
          - value: "https://nde.nl/ontology/hc/project/nde/heritage-digitization-2025"
            description: "Project funded by this call"
          - value: "https://nde.nl/ontology/hc/project/europeana/common-culture-2024"
            description: "Europeana project funded through Horizon Europe"
    
    comments:
      - "CallForApplication links FundingOrganisation to heritage custodian funding opportunities"
      - "Lifecycle tracked via CallForApplicationStatusEnum (ANNOUNCED through RESULTS_PUBLISHED)"
      - "CLOSING_SOON status based on date proximity (< 30 days to deadline)"
      - "Provenance tracked via web_observations linking to WebObservation instances"
      - "Maps to schema:Offer - funding as an offer to heritage institutions"
      - "Bidirectional link to Project via funded_projects ↔ funding_call"
    
    see_also:
      - "https://schema.org/Offer"
      - "https://schema.org/Grant"
      - "https://ec.europa.eu/info/funding-tenders/opportunities/portal"
      - "https://www.heritagefund.org.uk/"
      - "https://www.europanostra.org/our-work/awards/"
    
    examples:
      - value:
          call_id: "https://nde.nl/ontology/hc/call/ec/cl2-2025-heritage-01"
          call_title: "Cultural heritage, cultural and creative industries"
          call_short_name: "HORIZON-CL2-2025-HERITAGE-01"
          call_description: |
            This call supports research and innovation addressing cultural heritage
            preservation, digitisation, and access. Projects should develop new
            methods, technologies, and approaches for safeguarding tangible and
            intangible cultural heritage while promoting sustainable use and
            citizen engagement.
          call_status: "OPEN"
          call_url: "https://ec.europa.eu/info/funding-tenders/opportunities/portal/screen/opportunities/topic-details/horizon-cl2-2025-heritage-01"
          application_opening_date: "2025-01-15"
          application_deadline: "2025-09-16"
          results_expected_date: "2026-03-01"
          total_budget: "82.5M EUR"
          typical_grant_range: "2M-4M EUR per project"
          eligible_applicants:
            - "Public bodies"
            - "Research organisations"
            - "Higher education institutions"
            - "SMEs"
            - "Non-profit organisations"
            - "International organisations"
          eligible_countries:
            - "EU Member States"
            - "Horizon Europe Associated Countries"
          thematic_areas:
            - "Cultural heritage preservation"
            - "Digital heritage"
            - "Climate change impact on heritage"
            - "Heritage skills and crafts"
            - "Community engagement with heritage"
          heritage_types:
            - "Tangible heritage"
            - "Intangible heritage"
            - "Digital heritage"
            - "Documentary heritage"
          funding_rate: "100% for non-profit, 70% for for-profit"
          partnership_required: true
          minimum_partners: 3
          issuing_organisation: "https://nde.nl/ontology/hc/encompassing-body/funding/ec-rea"
          parent_programme: "Horizon Europe Cluster 2"
          programme_year: 2025
          contact_email: "REA-C2@ec.europa.eu"
          info_session_dates:
            - "2025-02-15 - Virtual info day"
            - "2025-04-10 - Brokerage event Brussels"
          keywords:
            - "cultural heritage"
            - "research"
            - "innovation"
            - "digitisation"
            - "preservation"
            - "EU funding"
            - "Horizon Europe"
          funded_projects:
            - "https://nde.nl/ontology/hc/project/europeana/common-culture-2024"
            - "https://nde.nl/ontology/hc/project/nde/heritage-digitization-2025"
        description: "Horizon Europe CL2 2025 Cultural Heritage call"
      
      - value:
          call_id: "https://nde.nl/ontology/hc/call/nlhf/medium-grants-2025-q4"
          call_title: "Medium grants - Heritage Fund"
          call_short_name: "MG-2025-Q4"
          call_description: |
            Medium grants support heritage projects seeking between £250,000 and
            £5 million. Projects must achieve outcomes for heritage, people, and
            communities. Suitable for conservation, interpretation, community
            engagement, and skills development projects.
          call_status: "OPEN"
          call_url: "https://www.heritagefund.org.uk/funding/medium-grants"
          application_deadline: "2025-12-31"
          typical_grant_range: "£250K-£5M"
          eligible_applicants:
            - "Not-for-profit organisations"
            - "Local authorities"
            - "Community groups"
            - "Heritage organisations"
          eligible_countries:
            - "England"
            - "Northern Ireland"
            - "Scotland"
            - "Wales"
          thematic_areas:
            - "Heritage conservation"
            - "Community engagement"
            - "Skills development"
            - "Nature conservation"
          heritage_types:
            - "Historic buildings"
            - "Natural heritage"
            - "Intangible heritage"
            - "Industrial heritage"
          co_funding_required: true
          partnership_required: false
          issuing_organisation: "https://nde.nl/ontology/hc/encompassing-body/funding/nlhf"
          parent_programme: "National Lottery Heritage Fund"
          programme_year: 2025
          keywords:
            - "UK heritage"
            - "lottery funding"
            - "conservation"
            - "community heritage"
        description: "National Lottery Heritage Fund medium grants"