# Format - Document/resource format class
#
# Created per slot_fixes.yaml migration for: format
# Creation date: 2026-01-22
# Rule compliance: 39 (RiC-O naming), 50 (ontology mapping), 53 (slot_fixes revision)

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

prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  dct: http://purl.org/dc/terms/
  schema: http://schema.org/
  premis: http://www.loc.gov/premis/rdf/v3/

default_prefix: hc

imports:
  - linkml:types
  - ../slots/description
  - ../slots/has_or_had_identifier
  - ../slots/has_or_had_label

classes:
  Format:
    class_uri: dct:MediaType
    description: |
      A structured representation of a document, file, or resource format.
      
      **USAGE**:
      Represents format specifications for:
      - Finding aids (EAD, PDF, HTML, MARC)
      - API responses (JSON, XML, RDF)
      - Media files (JPEG, MP3, MP4)
      - Transcripts and subtitles (VTT, SRT, TXT)
      
      **ONTOLOGY ALIGNMENT**:
      - **Primary** (`class_uri`): `dct:MediaType` - Dublin Core media type
      - **Related**: `schema:encodingFormat` - Schema.org encoding
      - **Related**: `premis:Format` - PREMIS preservation format
      
      **MIGRATION NOTE**:
      Created per slot_fixes.yaml revision (Rule 53, 2026-01-22).
      Replaces simple string-valued `format` slot with structured class.
      
    slots:
      - has_or_had_identifier
      - has_or_had_label
      - description
    
    attributes:
      format_id:
        identifier: true
        description: |
          Unique identifier for this format specification.
          Recommended: Use IANA media type URI or CURIE.
        range: uriorcurie
        slot_uri: dct:identifier
        examples:
          - value: "iana:application/xml"
            description: XML MIME type as CURIE
          - value: "https://www.iana.org/assignments/media-types/text/vtt"
            description: WebVTT format as full URI
      
      format_name:
        description: |
          Human-readable name of the format.
        range: string
        slot_uri: schema:name
        examples:
          - value: "Encoded Archival Description (EAD)"
          - value: "WebVTT Subtitle Format"
          - value: "JSON (JavaScript Object Notation)"
      
      mime_type:
        description: |
          IANA media type (MIME type) for this format.
        range: string
        slot_uri: dct:format
        pattern: "^[a-z]+/[a-z0-9.+-]+$"
        examples:
          - value: "application/xml"
          - value: "text/vtt"
          - value: "application/json"
      
      file_extension:
        description: |
          Common file extension(s) for this format.
        range: string
        multivalued: true
        examples:
          - value: ".xml"
          - value: ".ead"
          - value: ".vtt"
          - value: ".json"
      
      format_specification_url:
        description: |
          URL to the format's official specification or documentation.
        range: uri
        slot_uri: schema:url
        examples:
          - value: "https://www.loc.gov/ead/"
            description: EAD specification
          - value: "https://www.w3.org/TR/webvtt1/"
            description: WebVTT W3C specification
    
    exact_mappings:
      - dct:MediaType
    
    close_mappings:
      - schema:encodingFormat
      - premis:Format
    
    examples:
      - value:
          format_id: "iana:application/xml+ead"
          format_name: "Encoded Archival Description (EAD)"
          mime_type: "application/xml"
          file_extension:
            - ".xml"
            - ".ead"
          format_specification_url: "https://www.loc.gov/ead/"
        description: EAD finding aid format
      
      - value:
          format_id: "iana:text/vtt"
          format_name: "WebVTT (Web Video Text Tracks)"
          mime_type: "text/vtt"
          file_extension:
            - ".vtt"
          format_specification_url: "https://www.w3.org/TR/webvtt1/"
        description: WebVTT subtitle/caption format
      
      - value:
          format_id: "iana:application/pdf"
          format_name: "Portable Document Format (PDF)"
          mime_type: "application/pdf"
          file_extension:
            - ".pdf"
          format_specification_url: "https://www.iso.org/standard/75839.html"
        description: PDF document format
    
    annotations:
      custodian_types: '["*"]'
      custodian_types_rationale: "Format specifications applicable to all custodian types."
      specificity_score: "0.25"
      specificity_rationale: "Broadly applicable - formats used across all heritage custodian types."