332 lines
10 KiB
YAML
332 lines
10 KiB
YAML
id: https://nde.nl/ontology/hc/class/SearchAPI
|
|
name: search_api
|
|
title: SearchAPI 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
|
|
- ./DataServiceEndpoint
|
|
- ../slots/protocol
|
|
- ../slots/response_format
|
|
- ../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/PaginationMethodEnum
|
|
- ../enums/HTTPMethodEnum
|
|
- ../enums/SearchResponseFormatEnum
|
|
- ../slots/specificity_annotation
|
|
- ../slots/has_or_had_score # was: template_specificity - migrated per Rule 53 (2026-01-17)
|
|
- ../slots/specificity_annotation
|
|
- ../slots/has_or_had_score # was: template_specificity - migrated per Rule 53 (2026-01-17)
|
|
classes:
|
|
SearchAPI:
|
|
is_a: DataServiceEndpoint
|
|
class_uri: hc:SearchAPI
|
|
description: "REST/JSON search API endpoint for heritage collection discovery.\n\n**Purpose:**\n\nModels search APIs that\
|
|
\ provide programmatic access to collection search\nfunctionality. These APIs enable:\n- Custom search interface development\n\
|
|
- Integration with aggregation platforms\n- Automated data discovery\n- Faceted search and filtering\n\n**Common Patterns:**\n\
|
|
\nHeritage search APIs typically support:\n- **Full-text search**: Query across all fields\n- **Field-specific search**:\
|
|
\ Query specific metadata fields\n- **Faceted search**: Filter by category, date, type, etc.\n- **Pagination**: Navigate\
|
|
\ large result sets\n- **Sorting**: Order results by relevance, date, etc.\n\n**Example - Nationaal Archief Search API:**\n\
|
|
\n```yaml\nsearch_api:\n endpoint_name: \"Nationaal Archief Search API\"\n endpoint_url: \"https://www.nationaalarchief.nl/onderzoeken/api/zoeken\"\
|
|
\n protocol: REST\n query_parameters:\n - name: \"q\"\n type: \"string\"\n description: \"Full-text search\
|
|
\ query\"\n - name: \"from\"\n type: \"integer\"\n description: \"Pagination offset\"\n - name: \"size\"\
|
|
\n type: \"integer\"\n description: \"Results per page\"\n pagination_method: OFFSET_LIMIT\n max_results_per_page:\
|
|
\ 100\n response_format: JSON\n supports_facets: true\n facet_fields: [\"type\", \"periode\", \"archief\"]\n```\n\
|
|
\n**Response Structure:**\n\nMost heritage search APIs return JSON with:\n- `total`: Total number of matching records\n\
|
|
- `results`/`items`/`records`: Array of result objects\n- `facets`: Aggregation counts for filtering\n- `pagination`:\
|
|
\ Links or cursors for paging\n\n**See Also:**\n\n- OpenSearch: https://opensearch.org/\n- Hydra API vocabulary: https://www.hydra-cg.com/\n"
|
|
attributes:
|
|
has_or_had_url:
|
|
slot_uri: dcat:endpointURL
|
|
description: 'Search endpoint URL.
|
|
|
|
|
|
The base URL for search requests. Query parameters are appended.
|
|
|
|
|
|
Example: "https://www.nationaalarchief.nl/onderzoeken/api/zoeken"
|
|
|
|
'
|
|
range: uri
|
|
required: true
|
|
query_parameters:
|
|
slot_uri: hydra:mapping
|
|
description: "Query parameters supported by this search API.\n\nDocuments the available search parameters, their types,\
|
|
\ and usage.\n\nExample:\n```yaml\nquery_parameters:\n - name: \"q\"\n type: \"string\"\n required: true\n\
|
|
\ description: \"Full-text query\"\n - name: \"type\"\n type: \"string\"\n description: \"Filter by record\
|
|
\ type\"\n```\n"
|
|
range: SearchQueryParameter
|
|
multivalued: true
|
|
inlined_as_list: true
|
|
http_method:
|
|
slot_uri: hydra:method
|
|
description: 'HTTP method(s) supported for search requests.
|
|
|
|
|
|
Values:
|
|
|
|
- GET: Query parameters in URL (most common)
|
|
|
|
- POST: Query in request body (for complex queries)
|
|
|
|
- BOTH: Supports both methods
|
|
|
|
'
|
|
range: HTTPMethodEnum
|
|
pagination_method:
|
|
slot_uri: hydra:pageIndex
|
|
description: 'Pagination method used by this API.
|
|
|
|
|
|
Values:
|
|
|
|
- OFFSET_LIMIT: Uses offset/start and limit/size parameters
|
|
|
|
- PAGE_NUMBER: Uses page number and page size
|
|
|
|
- CURSOR: Uses cursor/token for stateful pagination
|
|
|
|
- LINK_HEADER: Uses HTTP Link headers (RFC 5988)
|
|
|
|
- NONE: No pagination (returns all results)
|
|
|
|
'
|
|
range: PaginationMethodEnum
|
|
max_results_per_page:
|
|
slot_uri: schema:maxValue
|
|
description: 'Maximum number of results per page.
|
|
|
|
|
|
The API may return fewer results, but never more.
|
|
|
|
|
|
Example: 100
|
|
|
|
'
|
|
range: integer
|
|
default_results_per_page:
|
|
slot_uri: schema:defaultValue
|
|
description: 'Default number of results returned per page if not specified.
|
|
|
|
|
|
Example: 20
|
|
|
|
'
|
|
range: integer
|
|
total_records:
|
|
slot_uri: schema:numberOfItems
|
|
description: 'Total number of searchable records (approximate).
|
|
|
|
|
|
Example: 15000000
|
|
|
|
'
|
|
range: integer
|
|
response_format:
|
|
slot_uri: dcterms:format
|
|
description: 'Primary response format.
|
|
|
|
|
|
Most modern APIs use JSON.
|
|
|
|
|
|
Values: JSON, XML, JSON_LD, HTML, CSV
|
|
|
|
'
|
|
range: SearchResponseFormatEnum
|
|
supports_facets:
|
|
slot_uri: schema:additionalProperty
|
|
description: 'Whether the API supports faceted search.
|
|
|
|
|
|
Faceted search allows filtering by categories (type, date, location, etc.)
|
|
|
|
with counts for each facet value.
|
|
|
|
'
|
|
range: boolean
|
|
facet_fields:
|
|
slot_uri: hydra:variable
|
|
description: 'Fields available for faceted filtering.
|
|
|
|
|
|
Example: ["type", "periode", "archief", "toegang"]
|
|
|
|
'
|
|
range: string
|
|
multivalued: true
|
|
supports_sorting:
|
|
slot_uri: schema:additionalProperty
|
|
description: 'Whether the API supports custom sorting of results.
|
|
|
|
'
|
|
range: boolean
|
|
sort_fields:
|
|
slot_uri: hydra:variable
|
|
description: 'Fields available for sorting.
|
|
|
|
|
|
Example: ["relevance", "date", "title", "created"]
|
|
|
|
'
|
|
range: string
|
|
multivalued: true
|
|
supports_boolean_operators:
|
|
slot_uri: schema:additionalProperty
|
|
description: 'Whether the API supports boolean operators (AND, OR, NOT) in queries.
|
|
|
|
'
|
|
range: boolean
|
|
supports_phrase_search:
|
|
slot_uri: schema:additionalProperty
|
|
description: 'Whether the API supports phrase search (exact match using quotes).
|
|
|
|
'
|
|
range: boolean
|
|
supports_wildcards:
|
|
slot_uri: schema:additionalProperty
|
|
description: 'Whether the API supports wildcard characters (* or ?).
|
|
|
|
'
|
|
range: boolean
|
|
supports_field_search:
|
|
slot_uri: schema:additionalProperty
|
|
description: 'Whether the API supports field-specific search (e.g., title:painting).
|
|
|
|
'
|
|
range: boolean
|
|
date_filter_format:
|
|
slot_uri: dcterms:temporal
|
|
description: 'Expected format for date filters.
|
|
|
|
|
|
Example: "YYYY-MM-DD", "ISO8601", "Unix timestamp"
|
|
|
|
'
|
|
range: string
|
|
result_schema_url:
|
|
slot_uri: schema:encodingFormat
|
|
description: 'URL to JSON Schema or documentation describing the result format.
|
|
|
|
|
|
Example: "https://api.example.org/schema/search-result.json"
|
|
|
|
'
|
|
range: uri
|
|
opensearch_description_url:
|
|
slot_uri: schema:potentialAction
|
|
description: 'URL to OpenSearch description document (if applicable).
|
|
|
|
|
|
Example: "https://example.org/opensearch.xml"
|
|
|
|
'
|
|
range: uri
|
|
example_query:
|
|
slot_uri: schema:workExample
|
|
description: 'Example search query demonstrating API usage.
|
|
|
|
|
|
Example: "/api/zoeken?q=foto&type=image&size=10"
|
|
|
|
'
|
|
range: string
|
|
comments:
|
|
- Primary interface for programmatic collection discovery
|
|
- Most heritage institutions expose REST/JSON search APIs
|
|
- Consider rate limits and pagination for large-scale harvesting
|
|
see_also:
|
|
- https://opensearch.org/
|
|
- https://www.hydra-cg.com/spec/latest/core/
|
|
slots:
|
|
- specificity_annotation
|
|
- has_or_had_score # was: template_specificity - migrated per Rule 53 (2026-01-17)
|
|
SearchQueryParameter:
|
|
class_uri: hydra:IriTemplateMapping
|
|
description: 'Describes a query parameter supported by a search API.
|
|
|
|
|
|
Documents the parameter name, type, whether it''s required,
|
|
|
|
and its purpose.
|
|
|
|
'
|
|
attributes:
|
|
name:
|
|
slot_uri: hydra:variable
|
|
description: 'Parameter name as used in the query string.
|
|
|
|
|
|
Example: "q", "type", "from", "size"
|
|
|
|
'
|
|
range: string
|
|
required: true
|
|
type:
|
|
slot_uri: hydra:property
|
|
description: 'Data type of the parameter value.
|
|
|
|
|
|
Values: string, integer, boolean, date, array
|
|
|
|
'
|
|
range: string
|
|
required:
|
|
slot_uri: hydra:required
|
|
description: 'Whether this parameter is required.
|
|
|
|
'
|
|
range: boolean
|
|
parameter_description:
|
|
slot_uri: dcterms:description
|
|
description: 'Human-readable description of the parameter.
|
|
|
|
|
|
Example: "Full-text search query"
|
|
|
|
'
|
|
range: string
|
|
default_value:
|
|
slot_uri: schema:defaultValue
|
|
description: 'Default value if not specified.
|
|
|
|
|
|
Example: "10" for a size parameter
|
|
|
|
'
|
|
range: string
|
|
allowed_values:
|
|
slot_uri: schema:valueReference
|
|
description: 'List of allowed values (for enumerated parameters).
|
|
|
|
|
|
Example: ["image", "document", "audio", "video"]
|
|
|
|
'
|
|
range: string
|
|
multivalued: true
|
|
example_value:
|
|
slot_uri: schema:workExample
|
|
description: 'Example value for this parameter.
|
|
|
|
|
|
Example: "amsterdam museum"
|
|
|
|
'
|
|
range: string
|
|
slots:
|
|
- specificity_annotation
|
|
- has_or_had_score # was: template_specificity - migrated per Rule 53 (2026-01-17)
|