kempersc/glam
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
glam/schemas/20251121/linkml/modules/classes/SearchAPI.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

332 lines
10 KiB
YAML
Raw Blame History

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:
search_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)
Reference in a new issue View git blame Copy permalink