glam/schemas/20251121/linkml/modules/classes/SearchAPI.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
- ../enums/HTTPMethodEnum
- ../enums/PaginationMethodEnum
- ../enums/SearchResponseFormatEnum
- ../metadata
- ../slots/has_or_had_score
- ../slots/response_format
- ../slots/specificity_annotation
- ./DataServiceEndpoint
- ./SpecificityAnnotation
- ./TemplateSpecificityScore
- ./TemplateSpecificityType
- ./TemplateSpecificityTypes
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
    annotations:
      specificity_score: 0.1
      specificity_rationale: Generic utility class/slot created during migration
      custodian_types: "['*']"
  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