kempersc/glam
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
glam/schemas/20251121/linkml/modules/classes/FileAPI.yaml
kempersc 626bd3a095 refactor(schemas): apply naming conventions to 261 class files 
- Apply Rule 39: RiC-O style hasOrHad*/isOrWas* for temporal slots
- Apply Rule 43: Singular noun convention (keywords → keyword)
- Update slot references to match renamed slot files
- Maintain schema integrity across all class definitions
2026-01-10 15:36:33 +01:00

287 lines
8.8 KiB
YAML
Raw Blame History

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
- ../slots/authentication_required
- ../slots/specificity_annotation
- ../slots/template_specificity
- ./SpecificityAnnotation
- ./TemplateSpecificityScores
classes:
FileAPI:
is_a: DataServiceEndpoint
class_uri: hc:FileAPI
description: |
File/asset retrieval API for downloading digital content.
**Purpose:**
Models endpoints that provide direct access to digital files
(images, documents, audio, video, 3D models) stored in heritage repositories.
**Distinction from Image Servers:**
- **FileAPI**: Downloads original or derivative files as-is
- **IIPImageServer**: Dynamic image delivery with zooming, tiling, region extraction
Use FileAPI when you need:
- Original/master files
- Fixed-resolution derivatives
- Non-image files (PDFs, audio, video, office documents)
**Example - Nationaal Archief File API:**
```yaml
file_api:
endpoint_name: "Nationaal Archief File API"
base_url: "https://service.archief.nl/gaf/api/file/v1/"
url_pattern: "{base_url}{uuid}/{level}/{format}"
version: "v1"
supported_levels:
- MASTER
- HIGH
- MEDIUM
- LOW
- THUMBNAIL
supported_format:
- image/jpeg
- image/png
- application/pdf
max_file_size_mb: 500
supports_range_requests: true
example_url: "https://service.archief.nl/gaf/api/file/v1/12345678.../high/jpeg"
```
**Use Cases:**
1. **Download master files**: Archival-quality preservation copies
2. **Generate derivatives**: Request specific size/format
3. **Batch harvesting**: Download all files for a record
4. **Streaming**: Audio/video delivery
**See Also:**
- Content-Disposition header for filename hints
- HTTP Range requests (RFC 7233) for partial downloads
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
supported_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: string
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
slot_usage:
protocol:
description: File APIs use REST protocol for downloads (DataServiceProtocolEnum.REST).
has_authentication_required_flag:
description: |
Master files often require authentication.
Thumbnails and low-res typically public.
specificity_annotation:
range: SpecificityAnnotation
inlined: true
template_specificity:
range: TemplateSpecificityScores
inlined: true
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
- template_specificity
enums:
ContentDispositionEnum:
description: |
HTTP Content-Disposition header behavior options.
permissible_values:
INLINE:
description: |
Content displayed inline in browser.
Header: Content-Disposition: inline
Browser attempts to render (images, PDFs).
ATTACHMENT:
description: |
Content downloaded as attachment.
Header: Content-Disposition: attachment; filename="example.pdf"
Browser prompts for download.
CONFIGURABLE:
description: |
Client can request either behavior.
Usually via query parameter: ?download=true
Reference in a new issue View git blame Copy permalink