4034c2a00a
- Removed unused slots from TaxonomicAuthority, TechnicalFeature, TelevisionArchive, TentativeWorldHeritageSite, Threat, TimeSpan, Title, TradeRegister, TradeUnionArchive, TradeUnionArchiveRecordSetType, TransferEvent, UNESCODomain, UnitIdentifier, UniversityArchive, UnspecifiedType, UserCommunity, Venue, Vereinsarchiv, Verlagsarchiv, VerlagsarchivRecordSetType, Version, Verwaltungsarchiv, VideoAnnotationTypes, VideoAudioAnnotation, VideoFrame, VideoPost, VideoSubtitle, VideoTextContent, Warehouse, WebArchive, WebClaim, WebClaimsBlock, WebLink, WebPortal, WebPortalTypes, WomensArchives, WordCount, WorldHeritageSite, WritingSystem, and XPathScore. - Introduced new slot is_or_was_retrieved_at for tracking data retrieval timestamps.
270 lines
7.8 KiB
YAML
270 lines
7.8 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
|
|
- ../enums/ContentDispositionEnum
|
|
- ../metadata
|
|
- ../slots/has_or_had_score
|
|
- ../slots/specificity_annotation
|
|
- ./DataServiceEndpoint
|
|
- ./SpecificityAnnotation
|
|
- ./TemplateSpecificityScore
|
|
- ./TemplateSpecificityType
|
|
- ./TemplateSpecificityTypes
|
|
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:
|
|
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: string
|
|
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
|
|
annotations:
|
|
specificity_score: 0.1
|
|
specificity_rationale: Generic utility class/slot created during migration
|
|
custodian_types: "['*']"
|