id: https://nde.nl/ontology/hc/class/DataFormat
name: DataFormat
title: Data Format
description: LinkML class definition for Data Format
prefixes:
  linkml: https://w3id.org/linkml/
  schema: http://schema.org/
  skos: http://www.w3.org/2004/02/skos/core#
  rico: https://www.ica.org/standards/RiC/ontology#
  wd: http://www.wikidata.org/entity/
# DataFormat - Class for data format specifications
#
# Created per slot_fixes.yaml migration for: data_format
# Creation date: 2026-01-22
# Rule compliance: 39 (RiC-O naming), 50 (ontology mapping), 53 (generic slot reuse), 0b (Type/Types)

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

prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  schema: http://schema.org/
  dct: http://purl.org/dc/terms/

default_prefix: hc

imports:
  - linkml:types
  - ../slots/has_or_had_type
  - ../slots/has_or_had_label
  - ../slots/has_or_had_description

classes:
  DataFormat:
    class_uri: hc:DataFormat
    description: |
      Specification of a data format for files, APIs, or data streams.
      
      **DEFINITION**:
      DataFormat captures format characteristics including type, media type,
      schema references, and encoding specifications.
      
      **USAGE**:
      - API response formats (JSON, XML, RDF)
      - File formats (CSV, Excel, PDF, TIFF)
      - Streaming protocols (MQTT, WebSocket payloads)
      - Archival formats (METS, EAD, MARC)
      
      **ONTOLOGY ALIGNMENT**:
      - **Primary** (`class_uri`): `hc:DataFormat` - Heritage Custodian class
      - **Close**: `dct:MediaTypeOrExtent` - Dublin Core media type
      - **Close**: `schema:encodingFormat` - Schema.org encoding
      
      **Common Format Types**:
      | Type | Media Type | Use Case |
      |------|------------|----------|
      | JSON | application/json | API responses, config |
      | XML | application/xml | Legacy APIs, metadata |
      | CSV | text/csv | Data exports, tabular |
      | RDF | application/rdf+xml | Linked data |
      | SensorML | application/xml | Sensor metadata |
      
      **Example**:
      ```yaml
      has_or_had_format:
        has_or_had_type: JsonFormat
        has_or_had_media_type: "application/json"
        has_or_had_encoding: "UTF-8"
      ```
      
    close_mappings:
      - dct:MediaTypeOrExtent
      - schema:encodingFormat
    
    slots:
      - has_or_had_type
      - has_or_had_label
      - has_or_had_description
      - has_or_had_media_type
      - has_or_had_encoding
      - has_or_had_schema_url
    
    slot_usage:
      has_or_had_type:
        range: DataFormatType
        description: |
          The format type classification.
          Links to DataFormatType taxonomy (JSON, XML, CSV, etc.).
        examples:
          - value: JsonFormat
            description: JSON format type
          - value: CsvFormat
            description: CSV format type
      has_or_had_label:
        range: Label
        inlined: true
        description: Human-readable name for the format.
        examples:
          - value:
              label_text: "JSON"
            description: Format label
      has_or_had_media_type:
        range: string
        description: |
          IANA media type (MIME type) for the format.
          See: https://www.iana.org/assignments/media-types/
        examples:
          - value: "application/json"
            description: JSON media type
          - value: "text/csv"
            description: CSV media type
      has_or_had_encoding:
        range: string
        description: Character encoding used (e.g., UTF-8, ISO-8859-1).
        examples:
          - value: "UTF-8"
            description: Unicode encoding
      has_or_had_schema_url:
        range: uri
        description: URL to schema definition (JSON Schema, XSD, etc.).
        examples:
          - value: "https://api.museum.nl/schemas/v1/climate.json"
            description: JSON Schema URL
    
    attributes:
      has_or_had_media_type:
        range: string
        description: IANA media type (MIME type).
      has_or_had_encoding:
        range: string
        description: Character encoding (e.g., UTF-8).
      has_or_had_schema_url:
        range: uri
        description: URL to schema definition.
    
    annotations:
      custodian_types: '["*"]'
      custodian_types_rationale: "Data format specifications apply to all custodian types with digital systems."
      specificity_score: 0.55
      specificity_rationale: "Moderately specific to digital platform and API contexts."

  # Type class for format taxonomy (Rule 0b: Type/Types pattern)
  DataFormatType:
    class_uri: hc:DataFormatType
    abstract: true
    description: |
      Abstract base class for data format type taxonomy.
      
      **Type/Types Pattern** (Rule 0b):
      - `DataFormatType` (this file): Abstract base class
      - `DataFormatTypes.yaml`: Concrete subclasses (JsonFormat, XmlFormat, etc.)
      
      Subclasses define specific format types used in heritage data systems.
      
    slots:
      - has_or_had_label
      - has_or_had_description
    
    annotations:
      custodian_types: '["*"]'
      custodian_types_rationale: "Format types applicable universally."