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 4319f38c05 Add archived slots for audience size, audience type, and capacity metrics 
- 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.
2026-01-17 18:53:23 +01:00

319 lines
11 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_format
# REMOVED 2026-01-15: ../slots/authentication_required - migrated to is_or_was_required
- ../slots/is_or_was_required
- ../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/DataServiceProtocolEnum
- ../enums/AuthenticationMethodEnum
- ../enums/EndpointStatusEnum
classes:
DataServiceEndpoint:
abstract: true
class_uri: dcat:DataService
slots:
# REMOVED 2026-01-15: authentication_required - migrated to is_or_was_required
- is_or_was_required
- protocol
- response_format
- specificity_annotation
- has_or_had_score # was: template_specificity - migrated per Rule 53 (2026-01-17)
description: "Abstract base class for API service endpoints exposed by heritage digital platforms.\n\n**Purpose:**\n\n\
Models 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 is_or_was_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.\n\n**Instance vs Type Architecture:**\n\
\nThis slot links an INSTANCE (DataServiceEndpoint) to its TYPE classification\n(DataServiceEndpointType), following\
\ the same architectural pattern as\nCustodian/CustodianType.\n\n```\nDataServiceEndpoint (INSTANCE) DataServiceEndpointType\
\ (TYPE)\n├── endpoint_url ├── protocol_name\n├── status ├── protocol_version\n\
├── is_or_was_required ├── specification_url\n└── endpoint_type ────────────────►└── has_or_had_format\n\
```\n\n**Why Both `protocol` and `endpoint_type`?**\n\n- `protocol` (enum): Simple string classification for quick\
\ filtering\n- `endpoint_type` (class reference): Rich type metadata with SKOS hierarchy,\n specification URLs,\
\ and semantic relationships\n\n**Example:**\n\n```yaml\ndata_service_endpoint:\n endpoint_id: \"https://nde.nl/hc/endpoint/na-oai-pmh\"\
\n endpoint_url: \"https://www.nationaalarchief.nl/onderzoeken/oai-pmh\"\n protocol: OAI_PMH \
\ # Simple enum (DataServiceProtocolEnum)\n endpoint_type: OAIPMHEndpointType # Rich type (DataServiceEndpointType\
\ subclass)\n```\n\nThis pattern mirrors:\n- `custodian_type` enum + `CustodianType` class on `Custodian`\n- `platform_type`\
\ enum + `DigitalPlatformType` class on `DigitalPlatform`\n"
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/
Reference in a new issue View git blame Copy permalink