4319f38c05
- Created new YAML files for audience size and audience type slots, defining their properties and annotations. - Added archived capacity slots including cubic meters, linear meters, item count, and descriptions, with appropriate URIs and ranges. - Introduced a template specificity slot for context-aware RAG filtering. - Consolidated capacity-related slots into a unified structure, including has_or_had_capacity, capacity_type, and capacity_value, with detailed descriptions and examples.
281 lines
8.2 KiB
YAML
281 lines
8.2 KiB
YAML
id: https://nde.nl/ontology/hc/class/FileAPI
|
|
name: file_api
|
|
title: FileAPI Class
|
|
prefixes:
|
|
linkml: https://w3id.org/linkml/
|
|
hc: https://nde.nl/ontology/hc/
|
|
dcat: http://www.w3.org/ns/dcat#
|
|
dcterms: http://purl.org/dc/terms/
|
|
schema: http://schema.org/
|
|
premis: http://www.loc.gov/premis/rdf/v3/
|
|
xsd: http://www.w3.org/2001/XMLSchema#
|
|
imports:
|
|
- linkml:types
|
|
- ../metadata
|
|
- ./DataServiceEndpoint
|
|
- ../slots/protocol
|
|
# REMOVED 2026-01-15: ../slots/authentication_required - migrated to is_or_was_required (inherited from DataServiceEndpoint)
|
|
- ../slots/specificity_annotation
|
|
- ../slots/has_or_had_score # was: template_specificity - migrated per Rule 53 (2026-01-17)
|
|
- ./SpecificityAnnotation
|
|
- ./TemplateSpecificityScore # was: TemplateSpecificityScores - migrated per Rule 53 (2026-01-17)
|
|
|
|
- ./TemplateSpecificityType
|
|
|
|
- ./TemplateSpecificityTypes
|
|
- ../enums/ContentDispositionEnum
|
|
classes:
|
|
FileAPI:
|
|
is_a: DataServiceEndpoint
|
|
class_uri: hc:FileAPI
|
|
description: "File/asset retrieval API for downloading digital content.\n\n**Purpose:**\n\nModels endpoints that provide\
|
|
\ direct access to digital files\n(images, documents, audio, video, 3D models) stored in heritage repositories.\n\n\
|
|
**Distinction from Image Servers:**\n\n- **FileAPI**: Downloads original or derivative files as-is\n- **IIPImageServer**:\
|
|
\ Dynamic image delivery with zooming, tiling, region extraction\n\nUse FileAPI when you need:\n- Original/master files\n\
|
|
- Fixed-resolution derivatives\n- Non-image files (PDFs, audio, video, office documents)\n\n**Example - Nationaal Archief\
|
|
\ File API:**\n\n```yaml\nfile_api:\n endpoint_name: \"Nationaal Archief File API\"\n base_url: \"https://service.archief.nl/gaf/api/file/v1/\"\
|
|
\n url_pattern: \"{base_url}{uuid}/{level}/{format}\"\n version: \"v1\"\n supported_levels:\n - MASTER\n -\
|
|
\ HIGH\n - MEDIUM\n - LOW\n - THUMBNAIL\n has_or_had_format: # was: supported_format - migrated 2026-01-16\n - image/jpeg\n - image/png\n - application/pdf\n\
|
|
\ max_file_size_mb: 500\n supports_range_requests: true\n example_url: \"https://service.archief.nl/gaf/api/file/v1/12345678.../high/jpeg\"\
|
|
\n```\n\n**Use Cases:**\n\n1. **Download master files**: Archival-quality preservation copies\n2. **Generate derivatives**:\
|
|
\ Request specific size/format\n3. **Batch harvesting**: Download all files for a record\n4. **Streaming**: Audio/video\
|
|
\ delivery\n\n**See Also:**\n\n- Content-Disposition header for filename hints\n- HTTP Range requests (RFC 7233) for\
|
|
\ partial downloads\n"
|
|
attributes:
|
|
base_url:
|
|
slot_uri: dcat:endpointURL
|
|
description: 'Base URL for file retrieval.
|
|
|
|
|
|
Individual files are accessed by appending identifiers.
|
|
|
|
|
|
Example: "https://service.archief.nl/gaf/api/file/v1/"
|
|
|
|
'
|
|
range: uri
|
|
required: true
|
|
url_pattern:
|
|
slot_uri: hydra:template
|
|
description: 'URL pattern for constructing file requests.
|
|
|
|
|
|
Use {placeholders} for dynamic parts:
|
|
|
|
- {uuid}: File identifier
|
|
|
|
- {level}: Quality level (master, high, low, thumbnail)
|
|
|
|
- {format}: File format (jpeg, png, pdf)
|
|
|
|
|
|
Example: "{base_url}{uuid}/{level}/{format}"
|
|
|
|
'
|
|
range: string
|
|
identifier_type:
|
|
slot_uri: dcterms:identifier
|
|
description: 'Type of identifier used to request files.
|
|
|
|
|
|
Values: UUID, HANDLE, DOI, ARK, LOCAL_ID, FILENAME
|
|
|
|
'
|
|
range: string
|
|
supported_levels:
|
|
slot_uri: schema:encodingFormat
|
|
description: 'Quality/resolution levels available.
|
|
|
|
|
|
Common levels:
|
|
|
|
- MASTER/ORIGINAL: Archival master file
|
|
|
|
- HIGH: High-resolution derivative
|
|
|
|
- MEDIUM: Medium resolution (web-suitable)
|
|
|
|
- LOW: Low resolution (fast loading)
|
|
|
|
- THUMBNAIL: Small preview image
|
|
|
|
|
|
Example: ["MASTER", "HIGH", "MEDIUM", "LOW", "THUMBNAIL"]
|
|
|
|
'
|
|
range: string
|
|
multivalued: true
|
|
has_or_had_format: # was: supported_format - migrated per Rule 53/56 (2026-01-16)
|
|
slot_uri: dcterms:format
|
|
description: 'File formats (MIME types) available for download.
|
|
|
|
|
|
May vary by content type and level.
|
|
|
|
|
|
Example:
|
|
|
|
- Images: ["image/jpeg", "image/png", "image/tiff"]
|
|
|
|
- Documents: ["application/pdf", "application/xml"]
|
|
|
|
- Audio: ["audio/mpeg", "audio/wav"]
|
|
|
|
- Video: ["video/mp4", "video/webm"]
|
|
|
|
'
|
|
range: uriorcurie
|
|
multivalued: true
|
|
required: true
|
|
max_file_size_mb:
|
|
slot_uri: schema:contentSize
|
|
description: 'Maximum file size available for download (in MB).
|
|
|
|
|
|
Larger files may require special access or batch delivery.
|
|
|
|
|
|
Example: 500
|
|
|
|
'
|
|
range: integer
|
|
typical_file_size_mb:
|
|
slot_uri: schema:contentSize
|
|
description: 'Typical file size for most downloads (in MB).
|
|
|
|
|
|
Helps clients estimate download times.
|
|
|
|
|
|
Example: 10
|
|
|
|
'
|
|
range: integer
|
|
supports_range_requests:
|
|
slot_uri: schema:additionalProperty
|
|
description: 'Whether HTTP Range requests are supported (RFC 7233).
|
|
|
|
|
|
Enables:
|
|
|
|
- Resumable downloads
|
|
|
|
- Partial content retrieval
|
|
|
|
- Streaming
|
|
|
|
|
|
Check for Accept-Ranges: bytes header.
|
|
|
|
'
|
|
range: boolean
|
|
supports_streaming:
|
|
slot_uri: schema:additionalProperty
|
|
description: 'Whether the API supports media streaming.
|
|
|
|
|
|
Relevant for audio/video content.
|
|
|
|
Enables progressive playback without full download.
|
|
|
|
'
|
|
range: boolean
|
|
content_disposition:
|
|
slot_uri: schema:additionalProperty
|
|
description: 'Content-Disposition header behavior.
|
|
|
|
|
|
Values:
|
|
|
|
- INLINE: Browser displays content
|
|
|
|
- ATTACHMENT: Browser downloads file
|
|
|
|
- CONFIGURABLE: Client can request either
|
|
|
|
'
|
|
range: ContentDispositionEnum
|
|
filename_in_url:
|
|
slot_uri: schema:additionalProperty
|
|
description: 'Whether original filename is included in URL.
|
|
|
|
|
|
Some APIs include filename for better download naming:
|
|
|
|
/api/file/v1/uuid/original.tif
|
|
|
|
'
|
|
range: boolean
|
|
supports_batch_download:
|
|
slot_uri: schema:additionalProperty
|
|
description: 'Whether batch/bulk download is supported.
|
|
|
|
|
|
May provide ZIP archives or async batch jobs.
|
|
|
|
'
|
|
range: boolean
|
|
batch_download_format:
|
|
slot_uri: dcterms:format
|
|
description: 'Format for batch downloads.
|
|
|
|
|
|
Example: "application/zip"
|
|
|
|
'
|
|
range: string
|
|
thumbnail_dimensions:
|
|
slot_uri: schema:width
|
|
description: 'Dimensions of thumbnail images (if thumbnail level available).
|
|
|
|
|
|
Format: "WIDTHxHEIGHT"
|
|
|
|
|
|
Example: "150x150"
|
|
|
|
'
|
|
range: string
|
|
watermark_applied:
|
|
slot_uri: schema:additionalProperty
|
|
description: 'Whether watermarks are applied to downloaded files.
|
|
|
|
|
|
May vary by access level or file type.
|
|
|
|
'
|
|
range: boolean
|
|
has_or_had_access_restriction:
|
|
slot_uri: dcterms:accessRights
|
|
description: 'Access restrictions on file downloads.
|
|
|
|
|
|
Examples:
|
|
|
|
- "Public access to all levels"
|
|
|
|
- "Master files require authentication"
|
|
|
|
- "Some collections IP-restricted"
|
|
|
|
'
|
|
range: string
|
|
example_url:
|
|
slot_uri: schema:workExample
|
|
description: 'Example URL for file download.
|
|
|
|
|
|
Example: "https://service.archief.nl/gaf/api/file/v1/12345678.../high/jpeg"
|
|
|
|
'
|
|
range: uri
|
|
comments:
|
|
- Essential for downloading digital content from heritage repositories
|
|
- Master files may have access restrictions
|
|
- Use Range requests for large file downloads
|
|
see_also:
|
|
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests
|
|
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition
|
|
slots:
|
|
- specificity_annotation
|
|
- has_or_had_score # was: template_specificity - migrated per Rule 53 (2026-01-17)
|