kempersc/glam
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
glam/schemas/20251121/linkml/modules/classes/DataServiceEndpoint.yaml
kempersc b34992b1d3 Migrate all 293 class files to ontology-aligned slots 
Extends migration to all class types (museums, libraries, galleries, etc.)

New slots added to class_metadata_slots.yaml:
- RiC-O: rico_record_set_type, rico_organizational_principle,
  rico_has_or_had_holder, rico_note
- Multilingual: label_de, label_es, label_fr, label_nl, label_it, label_pt
- Scope: scope_includes, scope_excludes, custodian_only,
  organizational_level, geographic_restriction
- Notes: privacy_note, preservation_note, legal_note

Migration script now handles 30+ annotation types.
All migrated schemas pass linkml-validate.

Total: 387 class files now use proper slots instead of annotations.
2026-01-06 12:24:54 +01:00

465 lines
16 KiB
YAML
Raw Blame History

id: https://nde.nl/ontology/hc/class/DataServiceEndpoint
name: data_service_endpoint
title: DataServiceEndpoint 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/
hydra: http://www.w3.org/ns/hydra/core#
xsd: http://www.w3.org/2001/XMLSchema#
imports:
- linkml:types
- ../metadata
- ./DataServiceEndpointType
- ../slots/protocol
- ../slots/response_formats
- ../slots/authentication_required
- ../slots/class_metadata_slots
classes:
DataServiceEndpoint:
abstract: true
class_uri: dcat:DataService
slots:
- authentication_required
- protocol
- response_formats
- specificity_annotation
- template_specificity
description: "Abstract base class for API service endpoints exposed by heritage\
\ digital platforms.\n\n**Purpose:**\n\nModels the technical API endpoints discovered\
\ at heritage institutions, enabling:\n- Machine-readable discovery of available\
\ APIs\n- Integration with aggregation platforms\n- Automated harvesting and\
\ synchronization\n- Developer documentation\n\n**DCAT 3 Alignment:**\n\nMaps\
\ to `dcat:DataService` which represents:\n- \"A collection of operations that\
\ provides access to one or more datasets or data processing functions\"\n-\
\ Has endpoint URL (dcat:endpointURL)\n- Has endpoint description/documentation\
\ (dcat:endpointDescription)\n- May serve one or more datasets (dcat:servesDataset)\n\
\n**Subclasses:**\n\n| Class | Protocol | Purpose |\n|-------|----------|---------|\n\
| OAIPMHEndpoint | OAI-PMH | Metadata harvesting |\n| SearchAPI | REST/JSON\
\ | Search and discovery |\n| METSAPI | REST/XML | METS document retrieval |\n\
| FileAPI | REST | File/asset download |\n| IIPImageServer | IIP/IIIF | Image\
\ serving |\n| EADDownload | HTTP | EAD finding aid export |\n\n**Example -\
\ Nationaal Archief APIs:**\n\n```yaml\ndigital_platform:\n platform_name:\
\ \"Nationaal Archief Website\"\n data_service_endpoints:\n - endpoint_type:\
\ OAIPMHEndpoint\n endpoint_url: \"https://www.nationaalarchief.nl/onderzoeken/oai-pmh\"\
\n protocol: OAI-PMH\n \n - endpoint_type: SearchAPI\n endpoint_url:\
\ \"https://www.nationaalarchief.nl/onderzoeken/api/zoeken\"\n protocol:\
\ REST\n response_formats: [\"application/json\"]\n \n - endpoint_type:\
\ IIPImageServer\n endpoint_url: \"https://service.archief.nl/iipsrv\"\n\
\ protocol: IIP\n```\n\n**Provenance:**\n\nDataServiceEndpoint instances\
\ MUST include discovery provenance:\n- When the endpoint was discovered\n-\
\ How it was discovered (web scrape, documentation, API testing)\n- Verification\
\ status\n"
exact_mappings:
- dcat:DataService
close_mappings:
- schema:WebAPI
- hydra:ApiDocumentation
attributes:
endpoint_id:
identifier: true
slot_uri: dcterms:identifier
description: |
Unique identifier for this data service endpoint.
Recommended format: URI combining platform ID and service type.
Example: "https://nde.nl/ontology/hc/endpoint/nationaalarchief-oai-pmh"
range: uriorcurie
required: true
endpoint_name:
slot_uri: schema:name
description: |
Human-readable name for this endpoint.
Examples:
- "Nationaal Archief OAI-PMH Endpoint"
- "Heritage Search API"
- "Image Server (IIP)"
range: string
required: true
endpoint_url:
slot_uri: dcat:endpointURL
description: |
Base URL of the service endpoint.
DCAT: dcat:endpointURL - "The root location or primary endpoint of the service"
This is the URL that clients use to access the service.
Examples:
- "https://www.nationaalarchief.nl/onderzoeken/oai-pmh"
- "https://api.europeana.eu/record/v2/"
- "https://service.archief.nl/iipsrv"
range: uri
required: true
endpoint_description_url:
slot_uri: dcat:endpointDescription
description: |
URL to machine-readable API documentation.
DCAT: dcat:endpointDescription - "A description of the service end-point"
May be:
- OpenAPI/Swagger specification (JSON/YAML)
- OAI-PMH Identify response
- WSDL document
- Human-readable documentation page
Examples:
- "https://api.example.org/openapi.json"
- "https://www.nationaalarchief.nl/onderzoeken/oai-pmh?verb=Identify"
range: uri
authentication_method:
slot_uri: schema:potentialAction
description: |
Authentication method required (if authentication_required is true).
Values from AuthenticationMethodEnum:
- NONE: No authentication
- API_KEY: API key in header or query parameter
- OAUTH2: OAuth 2.0
- BASIC: HTTP Basic Authentication
- IP_WHITELIST: IP address whitelist
- INSTITUTIONAL: Institutional login (Shibboleth, etc.)
range: AuthenticationMethodEnum
cors_enabled:
slot_uri: schema:additionalProperty
description: |
Whether CORS (Cross-Origin Resource Sharing) is enabled.
Important for browser-based JavaScript applications:
- true: Cross-origin requests allowed
- false: Same-origin only
- null: Unknown
range: boolean
rate_limit:
slot_uri: schema:rateValue
description: |
Rate limit description if applicable.
Free-text description of rate limiting policy.
Examples:
- "100 requests per minute"
- "1000 requests per day per API key"
- "No limit"
- "Unknown"
range: string
documentation_url:
slot_uri: schema:documentation
description: |
URL to human-readable documentation.
This is separate from endpoint_description_url which is machine-readable.
Examples:
- "https://pro.europeana.eu/resources/apis/record"
- "https://www.nationaalarchief.nl/onderzoeken/handleiding/api"
range: uri
status:
slot_uri: schema:serverStatus
description: |
Operational status of the endpoint.
Values from EndpointStatusEnum:
- ACTIVE: Endpoint is operational
- DEPRECATED: Endpoint works but will be removed
- BETA: Endpoint in testing/beta
- OFFLINE: Endpoint currently unavailable
- UNKNOWN: Status not verified
range: EndpointStatusEnum
last_verified:
slot_uri: schema:dateModified
description: |
Date when this endpoint was last verified to be operational.
ISO 8601 date format.
Example: "2025-12-14"
range: date
serves_dataset:
slot_uri: dcat:servesDataset
description: |
Dataset(s) that this service provides access to.
DCAT: dcat:servesDataset - "A collection of data that this data service can distribute"
References to DCAT Dataset identifiers or descriptions.
range: uriorcurie
multivalued: true
version:
slot_uri: schema:version
description: |
Version of the API or service.
Examples:
- "v2"
- "1.0.0"
- "2023-01"
range: string
discovery_provenance:
slot_uri: dcterms:provenance
description: |
Provenance information about how this endpoint was discovered.
Should include:
- Discovery date
- Discovery method (documentation, web scrape, API testing)
- Verification status
Free-text or structured provenance note.
range: string
endpoint_type:
slot_uri: dcterms:type
description: |
Classification of this endpoint from the DataServiceEndpointType taxonomy.
**Instance vs Type Architecture:**
This slot links an INSTANCE (DataServiceEndpoint) to its TYPE classification
(DataServiceEndpointType), following the same architectural pattern as
Custodian/CustodianType.
```
DataServiceEndpoint (INSTANCE) DataServiceEndpointType (TYPE)
├── endpoint_url ├── protocol_name
├── status ├── protocol_version
├── authentication_required ├── specification_url
└── endpoint_type ────────────────►└── typical_response_formats
```
**Why Both `protocol` and `endpoint_type`?**
- `protocol` (enum): Simple string classification for quick filtering
- `endpoint_type` (class reference): Rich type metadata with SKOS hierarchy,
specification URLs, and semantic relationships
**Example:**
```yaml
data_service_endpoint:
endpoint_id: "https://nde.nl/hc/endpoint/na-oai-pmh"
endpoint_url: "https://www.nationaalarchief.nl/onderzoeken/oai-pmh"
protocol: OAI_PMH # Simple enum (DataServiceProtocolEnum)
endpoint_type: OAIPMHEndpointType # Rich type (DataServiceEndpointType subclass)
```
This pattern mirrors:
- `custodian_type` enum + `CustodianType` class on `Custodian`
- `platform_type` enum + `DigitalPlatformType` class on `DigitalPlatform`
range: DataServiceEndpointType
required: false
comments:
- Links to DataServiceEndpointType taxonomy for rich type metadata
- Complements the simple `protocol` enum with class-based classification
- 'Follows Instance/Type pattern: Custodian→CustodianType, DigitalPlatform→DigitalPlatformType'
comments:
- Abstract class - use concrete subclasses (OAIPMHEndpoint, SearchAPI, etc.)
- Maps to DCAT 3 dcat:DataService for semantic interoperability
- Required for modeling API infrastructure of heritage digital platforms
see_also:
- https://www.w3.org/TR/vocab-dcat-3/#Class:Data_Service
- https://schema.org/WebAPI
- https://www.hydra-cg.com/spec/latest/core/
slot_usage:
specificity_annotation:
range: SpecificityAnnotation
inlined: true
template_specificity:
range: TemplateSpecificityScores
inlined: true
enums:
DataServiceProtocolEnum:
description: |
Protocols and standards implemented by data service endpoints.
permissible_values:
OAI_PMH:
description: |
Open Archives Initiative Protocol for Metadata Harvesting.
Standard for harvesting metadata from repositories.
Specification: http://www.openarchives.org/OAI/openarchivesprotocol.html
REST:
description: |
RESTful HTTP API.
Uses HTTP methods (GET, POST, etc.) with JSON/XML responses.
SOAP:
description: |
SOAP web services.
XML-based protocol with WSDL service description.
GRAPHQL:
description: |
GraphQL API.
Query language for APIs.
SPARQL:
description: |
SPARQL Protocol and RDF Query Language.
For querying RDF triple stores.
IIIF_IMAGE:
description: |
IIIF Image API.
International Image Interoperability Framework Image API.
Specification: https://iiif.io/api/image/
IIIF_PRESENTATION:
description: |
IIIF Presentation API.
For describing structure and layout of compound digital objects.
Specification: https://iiif.io/api/presentation/
IIIF_CONTENT_SEARCH:
description: |
IIIF Content Search API.
For searching within annotations.
Specification: https://iiif.io/api/search/
IIIF_CHANGE_DISCOVERY:
description: |
IIIF Change Discovery API.
For discovering changes in IIIF resources.
Specification: https://iiif.io/api/discovery/
IIP:
description: |
Internet Imaging Protocol.
Tile-based image delivery protocol.
Common implementations: IIPImage server.
ZOOMIFY:
description: |
Zoomify tile protocol.
Proprietary but widely-supported tiling format.
DEEPZOOM:
description: |
Microsoft Deep Zoom.
Tile-based image format for Seadragon viewers.
SRU:
description: |
Search/Retrieve via URL.
Standard search protocol from Library of Congress.
Specification: http://www.loc.gov/standards/sru/
Z39_50:
description: |
ANSI/NISO Z39.50 protocol.
Library search and retrieval protocol.
ATOM:
description: |
Atom Syndication Format.
XML-based feed format for content syndication.
RSS:
description: |
RSS (Really Simple Syndication).
XML-based feed format.
OPENSEARCH:
description: |
OpenSearch protocol.
Collection of simple formats for sharing search results.
Specification: https://opensearch.org/
WEBDAV:
description: |
WebDAV (Web Distributed Authoring and Versioning).
HTTP extension for collaborative editing.
FTP:
description: |
File Transfer Protocol.
For bulk file downloads.
AuthenticationMethodEnum:
description: |
Authentication methods for accessing API endpoints.
permissible_values:
NONE:
description: No authentication required (public access)
API_KEY:
description: |
API key authentication.
Key provided in HTTP header (e.g., X-API-Key) or query parameter.
API_KEY_HEADER:
description: API key in HTTP header
API_KEY_QUERY:
description: API key in URL query parameter
OAUTH2:
description: |
OAuth 2.0 authentication.
Token-based authentication with authorization flow.
OAUTH1:
description: OAuth 1.0a authentication
BASIC:
description: |
HTTP Basic Authentication.
Username/password in Authorization header.
BEARER_TOKEN:
description: |
Bearer token authentication.
JWT or opaque token in Authorization header.
IP_WHITELIST:
description: |
IP address whitelist.
Access restricted to specific IP ranges.
INSTITUTIONAL:
description: |
Institutional login.
Shibboleth, SAML, or similar federated authentication.
CLIENT_CERTIFICATE:
description: |
Client certificate authentication.
TLS/SSL client certificates.
DIGEST:
description: HTTP Digest Authentication
EndpointStatusEnum:
description: |
Operational status of an API endpoint.
permissible_values:
ACTIVE:
description: |
Endpoint is operational and accepting requests.
DEPRECATED:
description: |
Endpoint works but is deprecated.
Will be removed in future - migrate to new endpoint.
BETA:
description: |
Endpoint in testing/beta phase.
May change without notice.
ALPHA:
description: |
Endpoint in early alpha testing.
Not recommended for production use.
OFFLINE:
description: |
Endpoint currently unavailable.
May be temporary maintenance or permanent shutdown.
MAINTENANCE:
description: |
Endpoint temporarily offline for maintenance.
UNKNOWN:
description: |
Status not verified.
Needs testing to determine current status.
Reference in a new issue View git blame Copy permalink