# Project Plan Documentation Schema
# Semantic representation of project plans for ontology development work
#
# This schema models project plans following PROV-O, FOAF, and W3C ORG patterns
# with bilingual support (Dutch/English) for NDE heritage domain.
#
# Created: November 2025
# Purpose: Document the Heritage Custodian Ontology (Bronhouder Ontologie) project

id: https://nde.nl/ontology/doc/project-plan
name: project_plan_schema
title: Project Plan Documentation Schema
version: "0.1.0"
description: >-
  LinkML schema for representing ontology development project plans.
  Supports bilingual labels (nl/en) and aligns with PROV-O for provenance,
  FOAF for agents, and W3C ORG for organizational context.

prefixes:
  linkml: https://w3id.org/linkml/
  doc: https://nde.nl/ontology/doc/
  prov: http://www.w3.org/ns/prov#
  foaf: http://xmlns.com/foaf/0.1/
  org: http://www.w3.org/ns/org#
  schema: http://schema.org/
  dcterms: http://purl.org/dc/terms/
  skos: http://www.w3.org/2004/02/skos/core#
  time: http://www.w3.org/2006/time#
  tooi: https://identifier.overheid.nl/tooi/def/ont/
  rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns#

default_prefix: doc
default_range: string

imports:
  - linkml:types

# =============================================================================
# ENUMERATIONS
# =============================================================================

enums:
  WorkPackageStatusEnum:
    description: Status of a work package in the project lifecycle
    permissible_values:
      PLANNED:
        description: Work package is planned but not yet started
        meaning: prov:Plan
      IN_PROGRESS:
        description: Work package is currently being executed
      COMPLETED:
        description: Work package has been finished
      ON_HOLD:
        description: Work package is temporarily suspended
      CANCELLED:
        description: Work package has been cancelled

  DeliverableTypeEnum:
    description: Types of project deliverables
    permissible_values:
      ONTOLOGY:
        description: Ontology specification or extension
      SCHEMA:
        description: Data schema (LinkML, JSON Schema, SHACL, etc.)
      MAPPING:
        description: Mapping between vocabularies or datasets
      DOCUMENTATION:
        description: Technical or user documentation
      TEMPLATE:
        description: Reusable template (JSON-LD, validation rules, etc.)
      DATASET:
        description: Transformed or enriched dataset
      VALIDATION:
        description: Validation rules or quality checks
      PROFILE:
        description: Application profile for a standard

  OntologyAlignmentTypeEnum:
    description: Types of ontology alignment relationships
    permissible_values:
      EXTENSION:
        description: Extends or profiles the target ontology
        meaning: skos:broadMatch
      MAPPING:
        description: Maps concepts to target ontology
        meaning: skos:exactMatch
      INTEGRATION:
        description: Integrates with target ontology vocabulary
        meaning: skos:relatedMatch
      REFERENCE:
        description: References target ontology for consistency
        meaning: skos:closeMatch

  ScopeTypeEnum:
    description: Whether an item is in scope or out of scope
    permissible_values:
      IN_SCOPE:
        description: Included in current project scope
      OUT_OF_SCOPE:
        description: Explicitly excluded from current project scope
      FUTURE_SCOPE:
        description: Planned for future work beyond current project

# =============================================================================
# TYPES
# =============================================================================

types:
  Duration:
    typeof: integer
    description: Duration in hours
    uri: time:hours

  WeekNumber:
    typeof: integer
    description: ISO week number (1-53)
    minimum_value: 1
    maximum_value: 53

# =============================================================================
# CLASSES
# =============================================================================

classes:
  # ---------------------------------------------------------------------------
  # Project Plan (Root Container)
  # ---------------------------------------------------------------------------
  ProjectPlan:
    tree_root: true
    class_uri: prov:Plan
    description: >-
      A comprehensive project plan describing an ontology development effort.
      
      **PROV-O Alignment**:
      - prov:Plan - "A plan is an entity that represents a set of actions or steps 
        intended by one or more agents to achieve some goals."
      - The ProjectPlan is a prov:Plan that guides the prov:Activity instances
        (WorkPackages) that execute it.
      
      **Bilingual Support**:
      All labels and descriptions support both Dutch (@nl) and English (@en)
      language tags to serve NDE's international collaboration goals.
    
    exact_mappings:
      - prov:Plan
      - schema:Project
      - foaf:Project
    
    close_mappings:
      - org:OrganizationalCollaboration
    
    slots:
      - plan_id
      - plan_title
      - plan_title_en
      - plan_description
      - plan_description_en
      - assignment
      - assignment_en
      - focus_points
      - focus_points_en
      - work_packages
      - out_of_scope_items
      - timeline
      - total_hours
      - commissioning_organization
      - executing_agent
      - created_date
      - modified_date
    
    slot_usage:
      plan_id:
        identifier: true
        required: true
      plan_title:
        required: true
      work_packages:
        required: true
        inlined_as_list: true

  # ---------------------------------------------------------------------------
  # Work Package (Activity)
  # ---------------------------------------------------------------------------
  WorkPackage:
    class_uri: prov:Activity
    description: >-
      A discrete unit of work within a project plan with defined objectives,
      deliverables, and time allocation.
      
      **PROV-O Alignment**:
      - prov:Activity - "An activity is something that occurs over a period of time
        and acts upon or with entities; it may include consuming, processing,
        transforming, modifying, relocating, using, or generating entities."
      - Each WorkPackage is a prov:Activity that:
        - prov:wasInfluencedBy the ProjectPlan (guided by plan)
        - prov:generated Deliverable entities (produces outputs)
      
      **TOOI Alignment**:
      For Dutch government context, work packages can align with
      tooi:Werkzaamheid (activity) patterns.
    
    exact_mappings:
      - prov:Activity
      - schema:Action
    
    close_mappings:
      - tooi:Werkzaamheid
    
    slots:
      - wp_id
      - wp_number
      - wp_title
      - wp_title_en
      - wp_objective
      - wp_objective_en
      - deliverables
      - allocated_hours
      - status
      - ontology_alignments
    
    slot_usage:
      wp_id:
        identifier: true
        required: true
      wp_number:
        required: true
      wp_title:
        required: true
      allocated_hours:
        required: true
      deliverables:
        inlined_as_list: true
      ontology_alignments:
        inlined_as_list: true

  # ---------------------------------------------------------------------------
  # Deliverable (Entity)
  # ---------------------------------------------------------------------------
  Deliverable:
    class_uri: prov:Entity
    description: >-
      A tangible output produced by a work package.
      
      **PROV-O Alignment**:
      - prov:Entity - "An entity is a physical, digital, conceptual, or other kind
        of thing with some fixed aspects."
      - Each Deliverable is prov:wasGeneratedBy a WorkPackage (prov:Activity)
      - Deliverables may prov:wasDerivedFrom other entities (source ontologies)
    
    exact_mappings:
      - prov:Entity
      - schema:CreativeWork
    
    slots:
      - deliverable_id
      - deliverable_title
      - deliverable_title_en
      - deliverable_description
      - deliverable_description_en
      - deliverable_type
      - target_ontology
      - related_standards
    
    slot_usage:
      deliverable_id:
        identifier: true
        required: true
      deliverable_title:
        required: true
      deliverable_type:
        required: true
      target_ontology:
        multivalued: true
        inlined_as_list: true
      related_standards:
        multivalued: true
        inlined_as_list: true

  # ---------------------------------------------------------------------------
  # Ontology Alignment
  # ---------------------------------------------------------------------------
  OntologyAlignment:
    class_uri: skos:mappingRelation
    description: >-
      Documents how the project aligns with or extends an existing ontology.
      
      **SKOS Alignment**:
      Uses SKOS mapping relations (exactMatch, closeMatch, broadMatch, relatedMatch)
      to document semantic relationships between project outputs and base ontologies.
    
    exact_mappings:
      - skos:mappingRelation
    
    slots:
      - alignment_id
      - target_ontology_name
      - target_ontology_uri
      - alignment_type
      - alignment_description
      - alignment_description_en
    
    slot_usage:
      alignment_id:
        identifier: true
        required: true
      target_ontology_name:
        required: true
      alignment_type:
        required: true

  # ---------------------------------------------------------------------------
  # Out of Scope Item
  # ---------------------------------------------------------------------------
  OutOfScopeItem:
    class_uri: schema:Thing
    description: >-
      An item explicitly marked as outside the current project scope.
      Documents what is NOT included to clarify boundaries and manage expectations.
    
    slots:
      - item_id
      - item_title
      - item_title_en
      - item_description
      - item_description_en
      - scope_type
      - rationale
      - rationale_en
    
    slot_usage:
      item_id:
        identifier: true
        required: true
      item_title:
        required: true
      scope_type:
        required: true

  # ---------------------------------------------------------------------------
  # Project Timeline
  # ---------------------------------------------------------------------------
  ProjectTimeline:
    class_uri: time:TemporalEntity
    description: >-
      Temporal boundaries for the project execution.
      
      **OWL-Time Alignment**:
      Uses OWL-Time vocabulary for temporal description.
    
    exact_mappings:
      - time:TemporalEntity
      - time:ProperInterval
    
    slots:
      - start_week
      - end_week
      - start_year
      - end_year
      - duration_weeks
    
    slot_usage:
      start_week:
        required: true
      end_week:
        required: true
      start_year:
        required: true

  # ---------------------------------------------------------------------------
  # Agent (Organization or Person)
  # ---------------------------------------------------------------------------
  Agent:
    class_uri: prov:Agent
    description: >-
      An agent (person or organization) involved in the project.
      
      **PROV-O Alignment**:
      - prov:Agent - "An agent is something that bears some form of responsibility
        for an activity taking place."
    
    exact_mappings:
      - prov:Agent
      - foaf:Agent
    
    close_mappings:
      - org:Organization
      - foaf:Person
      - foaf:Organization
    
    slots:
      - agent_id
      - agent_name
      - agent_name_en
      - agent_type
      - agent_url
      - agent_identifiers
    
    slot_usage:
      agent_id:
        identifier: true
        required: true
      agent_name:
        required: true
      agent_identifiers:
        multivalued: true
        inlined_as_list: true

# =============================================================================
# SLOTS
# =============================================================================

slots:
  # ---------------------------------------------------------------------------
  # ProjectPlan slots
  # ---------------------------------------------------------------------------
  plan_id:
    slot_uri: dcterms:identifier
    range: uriorcurie
    description: Unique identifier for this project plan
  
  plan_title:
    slot_uri: dcterms:title
    range: string
    description: Title of the project plan (Dutch)
    annotations:
      language: nl
  
  plan_title_en:
    slot_uri: dcterms:title
    range: string
    description: Title of the project plan (English)
    annotations:
      language: en
  
  plan_description:
    slot_uri: dcterms:description
    range: string
    description: Detailed description of the project plan (Dutch)
    annotations:
      language: nl
  
  plan_description_en:
    slot_uri: dcterms:description
    range: string
    description: Detailed description of the project plan (English)
    annotations:
      language: en
  
  assignment:
    slot_uri: dcterms:abstract
    range: string
    description: The assignment/commission for the project (Dutch - OPDRACHT)
    annotations:
      language: nl
  
  assignment_en:
    slot_uri: dcterms:abstract
    range: string
    description: The assignment/commission for the project (English)
    annotations:
      language: en
  
  focus_points:
    slot_uri: skos:note
    range: string
    description: Key focus points and considerations (Dutch - AANDACHTSPUNT)
    annotations:
      language: nl
  
  focus_points_en:
    slot_uri: skos:note
    range: string
    description: Key focus points and considerations (English)
    annotations:
      language: en
  
  work_packages:
    slot_uri: prov:hadPlan
    range: WorkPackage
    multivalued: true
    inlined: true
    inlined_as_list: true
    description: Work packages that constitute this project plan
  
  out_of_scope_items:
    slot_uri: schema:hasPart
    range: OutOfScopeItem
    multivalued: true
    inlined: true
    inlined_as_list: true
    description: Items explicitly marked as out of scope
  
  timeline:
    slot_uri: dcterms:temporal
    range: ProjectTimeline
    inlined: true
    description: Project timeline with start/end dates
  
  total_hours:
    slot_uri: time:hours
    range: Duration
    description: Total allocated hours for the project
  
  commissioning_organization:
    slot_uri: prov:wasAttributedTo
    range: Agent
    inlined: true
    description: Organization that commissioned the project
  
  executing_agent:
    slot_uri: prov:wasAssociatedWith
    range: Agent
    inlined: true
    description: Agent (person or organization) executing the project
  
  created_date:
    slot_uri: dcterms:created
    range: date
    description: Date the project plan was created
  
  modified_date:
    slot_uri: dcterms:modified
    range: date
    description: Date the project plan was last modified

  # ---------------------------------------------------------------------------
  # WorkPackage slots
  # ---------------------------------------------------------------------------
  wp_id:
    slot_uri: dcterms:identifier
    range: uriorcurie
    description: Unique identifier for this work package
  
  wp_number:
    slot_uri: schema:position
    range: integer
    description: Sequential number of the work package (1, 2, 3...)
  
  wp_title:
    slot_uri: dcterms:title
    range: string
    description: Title of the work package (Dutch)
    annotations:
      language: nl
  
  wp_title_en:
    slot_uri: dcterms:title
    range: string
    description: Title of the work package (English)
    annotations:
      language: en
  
  wp_objective:
    slot_uri: dcterms:abstract
    range: string
    description: Objective of the work package (Dutch - Doelstelling)
    annotations:
      language: nl
  
  wp_objective_en:
    slot_uri: dcterms:abstract
    range: string
    description: Objective of the work package (English)
    annotations:
      language: en
  
  deliverables:
    slot_uri: prov:generated
    range: Deliverable
    multivalued: true
    inlined: true
    inlined_as_list: true
    description: Deliverables produced by this work package
  
  allocated_hours:
    slot_uri: time:hours
    range: Duration
    description: Hours allocated to this work package
  
  status:
    slot_uri: schema:eventStatus
    range: WorkPackageStatusEnum
    description: Current status of the work package
  
  ontology_alignments:
    slot_uri: skos:relatedMatch
    range: OntologyAlignment
    multivalued: true
    inlined: true
    inlined_as_list: true
    description: Ontology alignments relevant to this work package

  # ---------------------------------------------------------------------------
  # Deliverable slots
  # ---------------------------------------------------------------------------
  deliverable_id:
    slot_uri: dcterms:identifier
    range: uriorcurie
    description: Unique identifier for this deliverable
  
  deliverable_title:
    slot_uri: dcterms:title
    range: string
    description: Title of the deliverable (Dutch)
    annotations:
      language: nl
  
  deliverable_title_en:
    slot_uri: dcterms:title
    range: string
    description: Title of the deliverable (English)
    annotations:
      language: en
  
  deliverable_description:
    slot_uri: dcterms:description
    range: string
    description: Description of the deliverable (Dutch)
    annotations:
      language: nl
  
  deliverable_description_en:
    slot_uri: dcterms:description
    range: string
    description: Description of the deliverable (English)
    annotations:
      language: en
  
  deliverable_type:
    slot_uri: dcterms:type
    range: DeliverableTypeEnum
    description: Type of deliverable
  
  target_ontology:
    slot_uri: skos:relatedMatch
    range: string
    multivalued: true
    description: Target ontologies this deliverable relates to
  
  related_standards:
    slot_uri: dcterms:conformsTo
    range: string
    multivalued: true
    description: Standards this deliverable conforms to or relates to

  # ---------------------------------------------------------------------------
  # OntologyAlignment slots
  # ---------------------------------------------------------------------------
  alignment_id:
    slot_uri: dcterms:identifier
    range: uriorcurie
    description: Unique identifier for this alignment
  
  target_ontology_name:
    slot_uri: skos:prefLabel
    range: string
    description: Name of the target ontology
  
  target_ontology_uri:
    slot_uri: dcterms:source
    range: uri
    description: URI of the target ontology
  
  alignment_type:
    slot_uri: skos:mappingRelation
    range: OntologyAlignmentTypeEnum
    description: Type of alignment relationship
  
  alignment_description:
    slot_uri: dcterms:description
    range: string
    description: Description of the alignment (Dutch)
    annotations:
      language: nl
  
  alignment_description_en:
    slot_uri: dcterms:description
    range: string
    description: Description of the alignment (English)
    annotations:
      language: en

  # ---------------------------------------------------------------------------
  # OutOfScopeItem slots
  # ---------------------------------------------------------------------------
  item_id:
    slot_uri: dcterms:identifier
    range: uriorcurie
    description: Unique identifier for this out-of-scope item
  
  item_title:
    slot_uri: dcterms:title
    range: string
    description: Title of the out-of-scope item (Dutch)
    annotations:
      language: nl
  
  item_title_en:
    slot_uri: dcterms:title
    range: string
    description: Title of the out-of-scope item (English)
    annotations:
      language: en
  
  item_description:
    slot_uri: dcterms:description
    range: string
    description: Description of the out-of-scope item (Dutch)
    annotations:
      language: nl
  
  item_description_en:
    slot_uri: dcterms:description
    range: string
    description: Description of the out-of-scope item (English)
    annotations:
      language: en
  
  scope_type:
    slot_uri: schema:category
    range: ScopeTypeEnum
    description: Whether item is out of scope or future scope
  
  rationale:
    slot_uri: skos:note
    range: string
    description: Rationale for exclusion (Dutch)
    annotations:
      language: nl
  
  rationale_en:
    slot_uri: skos:note
    range: string
    description: Rationale for exclusion (English)
    annotations:
      language: en

  # ---------------------------------------------------------------------------
  # ProjectTimeline slots
  # ---------------------------------------------------------------------------
  start_week:
    slot_uri: time:week
    range: WeekNumber
    description: Starting week number (ISO week)
  
  end_week:
    slot_uri: time:week
    range: WeekNumber
    description: Ending week number (ISO week)
  
  start_year:
    slot_uri: time:year
    range: integer
    description: Starting year
  
  end_year:
    slot_uri: time:year
    range: integer
    description: Ending year
  
  duration_weeks:
    slot_uri: time:weeks
    range: integer
    description: Duration in weeks

  # ---------------------------------------------------------------------------
  # Agent slots
  # ---------------------------------------------------------------------------
  agent_id:
    slot_uri: dcterms:identifier
    range: uriorcurie
    description: Unique identifier for this agent
  
  agent_name:
    slot_uri: foaf:name
    range: string
    description: Name of the agent (Dutch)
    annotations:
      language: nl
  
  agent_name_en:
    slot_uri: foaf:name
    range: string
    description: Name of the agent (English)
    annotations:
      language: en
  
  agent_type:
    slot_uri: rdf:type
    range: string
    description: Type of agent (Person, Organization, etc.)
  
  agent_url:
    slot_uri: foaf:homepage
    range: uri
    description: Homepage URL of the agent
  
  agent_identifiers:
    slot_uri: dcterms:identifier
    range: string
    multivalued: true
    description: External identifiers (Wikidata, ISNI, etc.)