hsda-secure-search-road-map-suggestion

hsda-secure-search-road-map-suggestion.yaml

swagger: '2.0'
info:
  title: "HSDA"
  description: "HSDA Secure Search Road Map Suggestion"
  contact:
    name: rasmus-storjohann-PG
    url: https://github.com/rasmus-storjohann-PG
  version: v1.2
host: {host}
basePath: {basePath}
schemes:
- https
produces:
- application/json
paths:
  /organizations/secure-search/:
   post:
      summary: Organizations Secure Search
      description:  Search for organizations using a POST of an organization definition using the body.
      operationId: secureSearchOrganizations
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/organization_complete'
      responses:
        '200':
          description: Service Response
          schema:
            type: array
            items:
              $ref: "#/definitions/organization_complete"   
  /locations/secure-search/:
   post:
      summary: Locations Secure Search
      description: Search for locations using a POST of an location definition using the body.
      operationId: secureSearchLocations
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/location_complete'
      responses:
        '200':
          description: Service Response
          schema:
            type: array
            items:
              $ref: "#/definitions/location_complete"              
  /services/secure-search/:
   post:
      summary: Services Secure Search
      description: Search for locations using a POST of an location definition using the body.
      operationId: secureSearchServices
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/service_complete'
      responses:
        '200':
          description: Service Response
          schema:
            type: array
            items:
              $ref: "#/definitions/service_complete"
definitions:
  organization_complete:
    description: 'Provides a full description of an organization entity'
    properties:
      id:
        description: 'Each organization must have a unique identifier.'
        type: string
      name:
        description: 'The official or public name of the organization.'
        type: string
      alternate_name:
        description: 'Alternative or commonly used name for the organization.'
        type: string
      description:
        description: 'A brief summary about the organization. It can contain markup such as HTML or Markdow.'
        type: string
      email:
        description: 'The contact e-mail address for the organization.'
        type: string
      url:
        description: 'The URL (website address) of the organization.'
        type: string
      tax_status:
        description: 'Government assigned tax designation for for tax-exempt organizations.'
        type: string
      tax_id:
        description: 'A government issued identifier used for the purpose of tax administration.'
        type: string
      year_incorporated:
        description: 'The year in which the organization was legally formed.'
        type: string
      legal_status:
        description: 'The legal status defines the conditions that an organization is operating under; e.g. non-profit, private corporation or a government organization.'
        type: string
      contacts:
        description: 'The contacts sub-subresource.'
        type: "array"
        items:
          $ref: "#/definitions/contact"
      funding:
        description: 'The funding sub-subresource.'
        type: "array"
        items:
          $ref: "#/definitions/funding"
      locations:
        type: "array"
        items:
          $ref: "#/definitions/location"
      programs:
        type: "array"
        items:
          $ref: "#/definitions/program"
      services:
        type: "array"
        items:
          $ref: "#/definitions/service"
    required:
      - id
      - description
  location_complete:
    description: 'Full location details of an organization.'
    properties:
      id:
        description: 'Each location must have a unique identifier.'
        type: string
      organization_id:
        description: 'Each location must belong to a single organization. The identifier of the organization should be given here.'
        type: string
      name:
        description: 'The name of the location.'
        type: string
      alternate_name:
        description: 'An alternative name for the location.'
        type: string
      description:
        description: 'A description of this location.'
        type: string
      transportation:
        description: 'A description of the access to public or private transportation to and from the location.'
        type: string
      latitude:
        description: 'Y coordinate of location expressed in decimal degrees in WGS84 datum.'
        type: string
      longitude:
        description: 'X coordinate of location expressed in decimal degrees in WGS84 datum.'
        type: string
      regular_schedule:
        type: "array"
        items:
          $ref: "#/definitions/regular_schedule"
      holiday_schedule:
        type: "array"
        items:
          $ref: "#/definitions/holiday_schedule"
      languages:
        type: "array"
        items:
          $ref: "#/definitions/language"
      postal_address:
        type: "array"
        items:
          $ref: "#/definitions/postal_address"
      physical_address:
        type: "array"
        items:
          $ref: "#/definitions/physical_address"
      phones:
        type: "array"
        items:
          $ref: "#/definitions/phone"
      service:
        type: "array"
        items:
          $ref: "#/definitions/service"
      accessibility_for_disabilities:
        type: "array"
        items:
          $ref: "#/definitions/accessibility_for_disabilities"
    required:
      - id      
  service_complete:
    description: Full details about a service.
    properties:
      id:
        description: 'Each service must have a unique identifier.'
        type: string
      organization_id:
        description: 'The identifier of the organization that provides this service.'
        type: string
      program_id:
        description: 'The identifier of the program this service is delivered under.'
        type: string
      location_id:
        description: 'The identifier of the location where this service is delivered.'
        type: string
      name:
        description: 'The official or public name of the service.'
        type: string
      alternate_name:
        description: 'Alternative or commonly used name for a service.'
        type: string
      description:
        description: 'A description of the service.'
        type: string
      url:
        description: 'URL of the service.'
        type: string
      email:
        description: 'Email address for the service.'
        type: string
      status:
        description: 'The current status of the service.'
        type: string
      interpretation_services:
        description: 'A description of any interpretation services available for accessing this service.'
        type: string
      application_process:
        description: 'The steps needed to access the service.'
        type: string
      wait_time:
        description: 'Time a client may expect to wait before receiving a service.'
        type: string
      accreditations:
        description: 'Details of any accreditations. Accreditation is the formal evaluation of an organization or program against best practice standards set by an accrediting organization.'
        type: string
      licenses:
        description: 'An organization may have a license issued by a government entity to operate legally. A list of any such licenses can be provided here.'
        type: string
      contacts:
        type: "array"
        items:
          $ref: "#/definitions/contact"
      eligibility:
        type: "array"
        items:
          $ref: "#/definitions/eligibility"
      fees:
        type: "array"
        items:
          $ref: "#/definitions/fee"
      funding:
        type: "array"
        items:
          $ref: "#/definitions/funding"
      regular_schedule:
        type: "array"
        items:
          $ref: "#/definitions/regular_schedule"
      holiday_schedule:
        type: "array"
        items:
          $ref: "#/definitions/holiday_schedule"
      languages:
        type: "array"
        items:
          $ref: "#/definitions/language"
      payment_accepted:
        type: "array"
        items:
          $ref: "#/definitions/payment_accepted"
      phones:
        type: "array"
        items:
          $ref: "#/definitions/phone"
      required_documents:
        type: "array"
        items:
          $ref: "#/definitions/required_document"
      service_area:
        type: "array"
        items:
          $ref: "#/definitions/service_area"
    required:
      - id
      - organization_id
      - name
      - status
  contact:
    description: 'Details of the named contacts for services and organizations.'
    properties:
      id:
        description: 'Each contact must have a unique identifier.'
        type: string
      organization_id:
        description: 'The identifier of the organization for which this is a contact.'
        type: string
      service_id:
        description: 'The identifier of the service for which this is a contact.'
        type: string
      service_at_location_id:
        description: 'The identifier of the ‘service at location’ table entry, when this contact is specific to a service in a particular location.'
        type: string
      name:
        description: 'The name of the person.'
        type: string
      title:
        description: 'The job title of the person.'
        type: string
      department:
        description: 'The department that the person is part of.'
        type: string
      email:
        description: 'The email address of the person.'
        type: string
    required:
      - id
  location:
    description: 'Details of the locations where organizations operate. Locations may be virtual, and one organization may have many locations.'
    type: object
    properties:
      id:
        description: 'Each location must have a unique identifier.'
        type: string
      organization_id:
        description: 'Each location must belong to a single organization. The identifier of the organization should be given here.'
        type: string
      name:
        description: 'The name of the location.'
        type: string
      alternate_name:
        description: 'An alternative name for the location.'
        type: string
      description:
        description: 'A description of this location.'
        type: string
      transportation:
        description: 'A description of the access to public or private transportation to and from the location.'
        type: string
      latitude:
        description: 'Y coordinate of location expressed in decimal degrees in WGS84 datum.'
        type: string
      longitude:
        description: 'X coordinate of location expressed in decimal degrees in WGS84 datum.'
        type: string
    required:
      - id
      - name      
  service:
    description: 'Services are provided by organizations to a range of different groups. Details on where each service is delivered are contained in the services_at_location table.'
    properties:
      id:
        description: 'Each service must have a unique identifier.'
        type: string
      organization_id:
        description: 'The identifier of the organization that provides this service.'
        type: string
      program_id:
        description: 'The identifier of the program this service is delivered under.'
        type: string
      location_id:
        description: 'The identifier of the location where this service is delivered.'
        type: string
      name:
        description: 'The official or public name of the service.'
        type: string
      alternate_name:
        description: 'Alternative or commonly used name for a service.'
        type: string
      description:
        description: 'A description of the service.'
        type: string
      url:
        description: 'URL of the service.'
        type: string
      email:
        description: 'Email address for the service.'
        type: string
      status:
        description: 'The current status of the service.'
        type: string
      interpretation_services:
        description: 'A description of any interpretation services available for accessing this service.'
        type: string
      application_process:
        description: 'The steps needed to access the service.'
        type: string
      wait_time:
        description: 'Time a client may expect to wait before receiving a service.'
        type: string
      fees:
        description: 'Details of any charges for service users to access this service.'
        type: string
      accreditations:
        description: 'Details of any accreditations. Accreditation is the formal evaluation of an organization or program against best practice standards set by an accrediting organization.'
        type: string
      licenses:
        description: 'An organization may have a license issued by a government entity to operate legally. A list of any such licenses can be provided here.'
        type: string      
  physical_address:
    description: 'Describes a physical address of a location'
    properties:
      id:
        description: 'Each physical address must have a unique identifier.'
        type: string
      location_id:
        description: 'The identifier of the location for which this is the address.'
        type: string
      attention:
        description: 'The person or entity whose attention should be sought at the location.'
        type: string
      address_1:
        description: 'The first line of the address.'
        type: string
      address_2:
        description: 'The second line of the address.'
        type: string
      address_3:
        description: 'The third line of the address.'
        type: string
      address_4:
        description: 'The fourth line of the address.'
        type: string
      city:
        description: 'The city in which the address is located.'
        type: string
      region:
        description: 'The region in which the address is located (optional).'
        type: string
      state_province:
        description: 'The state or province in which the address is located.'
        type: string
      postal_code:
        description: 'The postal code for the address.'
        type: string
      country:
        description: 'The country in which the address is located. This should be given as an ISO 3361-1 country code (two letter abbreviation).'
        type: string
    required:
      - id
      - address_1
      - city
      - state_province
      - postal_code
      - country
  postal_address:
    description: 'Contains the postal addresses for mail to a certain location. This may differ from the physical location.'
    properties:
      id:
        description: 'Each postal address must have a unique identifier.'
        type: string
      location_id:
        description: 'The identifier of the location for which this is the postal address.'
        type: string
      attention:
        description: 'The person or entity for whose attention mail should be marked.'
        type: string
      address_1:
        description: 'The first line of the address.'
        type: string
      address_2:
        description: 'The second line of the address.'
        type: string
      address_3:
        description: 'The third line of the address.'
        type: string
      address_4:
        description: 'The fourth line of the address.'
        type: string
      city:
        description: 'The city in which the address is located.'
        type: string
      region:
        description: 'The region in which the address is located (optional).'
        type: string
      state_province:
        description: 'The state or province in which the address is located.'
        type: string
      postal_code:
        description: 'The postal code for the address.'
        type: string
      country:
        description: 'The country in which the address is located.'
        type: string
    required:
      - id
  program:
    description: 'Some organizations organise their services into programs. A program brings together a number of related services.'
    properties:
      id:
        description: 'Each program must have a unique identifier.'
        type: string
      organization_id:
        description: 'Each program must belong to a single organization. The identifier of the organization should be given here.'
        type: string
      name:
        description: 'The name of the program.'
        type: string
      alternate_name:
        description: 'NeAn alternative name for the program.'
        type: string
    required:
      - id
      - organization_id
      - name      
  eligibility:
    description: 'Details of eligibility criteria for particular services'
    properties:
      id:
        description: 'Each entry must have a unique identifier.'
        type: string
      service_id:
        description: 'The identifier of the service for which this entry describes the eligibility criteria.'
        type: string
      eligibility:
        description: 'The rules or guidelines that determine who can receive the service.'
        type: string
    required:
      - id
  fee:
    description: 'Details of charges imposed by services'
    properties:
      id:
        description: 'Each entry must have a unique identifier.'
        type: string
      service_id:
        description: 'The identifier of the service for which this entry describes the costs of service.'
        type: string
      fee:
        description: 'A listing of the costs of services, including free ones.'
        type: string
    required:
      - id
  funding:
    description: 'Describes a source of funding for a service or organisation'
    properties:
      id:
        description: 'Each entry must have a unique identifier.'
        type: string
      organization_id:
        description: 'The identifier of the organization for which this entry describes the source of funding.'
        type: string
      service_id:
        description: 'The identifier of the service for which this entry describes the source of funding.'
        type: string
      source:
        description: 'Source of funds for organization or service.'
        type: string
    required:
      - id
  holiday_schedule:
    description: 'Details of when a service or location is open during holidays. Each entry in the table describes a period of one or more days, and the operating times on those days.'
    properties:
      id:
        description: 'Each entry must have a unique identifier.'
        type: string
      service_id:
        description: 'The identifier of the service for which this is the holiday schedule.'
        type: string
      location_id:
        description: 'The identifier of the location for which this is the holiday schedule.'
        type: string
      service_at_location_id:
        description: 'The identifier of the ‘service at location’ table entry, when this schedule is specific to a service in a particular location.'
        type: string
      closed:
        description: 'Indicates if a service or location is closed during a public holiday.'
        type: boolean
      opens_at:
        description: 'The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.'
        type: string
      closes_at:
        description: 'The time when a service or location closes. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.'
        type: string
      start_date:
        description: 'The first day that a service or location is closed during a public or private holiday.'
        type: string
      end_date:
        description: 'The last day that a service or location is closed during a public or private holiday.'
        type: string
    required:
      - id
      - closed
      - start_date
      - end_date
  intepretation_services:
    description: 'Describes interpretation services offered in different languages'
    properties:
      id:
        description: 'Each service must have a unique identifier.'
        type: string
      service_id:
        description: 'The identifier of the services for which the entry describes the interpretation services available.'
        type: string
      language:
        description: 'Languages, other than English, for which interpretation is available. Languages are listed as ISO639-1 codes.'
        type: string
    required:
      - id
  language:
    description: 'Details of the languages that are spoken at locations or services. This does not include languages which can only be used with intepretation.'
    properties:
      id:
        description: 'Each language must have a unique identifier.'
        type: string
      service_id:
        description: 'The identifier of the service for which the entry describes the languages in which services are delivered.'
        type: string
      location_id:
        description: 'The identifier of the location for which the entry describes the languages in which services are delivered.'
        type: string
      language:
        description: 'Languages, other than English, in which the service is delivered. Languages are listed as ISO639-1 codes..'
        type: string
    required:
      - id      
  regular_schedule:
    description: 'Details of when a service or location is open under normal circumstances. Each entry in the table can relate to one and only one day of the week.'
    properties:
      id:
        description: 'Each entry must have a unique identifier.'
        type: string
      service_id:
        description: 'The identifier of the service for which this is the regular schedule.'
        type: string
      location_id:
        description: 'The identifier of the location for which this is the regular schedule.'
        type: string
      service_at_location_id:
        description: 'The identifier of the ‘service at location’ table entry, when this schedule is specific to a service in a particular location.'
        type: string
      weekday:
        description: 'The day of the week that this entry relates to.'
        type: string
      opens_at:
        description: 'The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.'
        type: string
      closes_at:
        description: 'The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.'
        type: string
    required:
      - id
      - weekday      
  payment_accepted:
    description: 'Details of the methods of payment that can be used in order to pay for services'
    properties:
      id:
        description: 'Each entry must have a unique identifier.'
        type: string
      service_id:
        description: 'The identifier of the services for which the entry describes the accepted payment methods.'
        type: string
      payment:
        description: 'The methods of payment accepted for the service.'
        type: string
    required:
      - id
  phone:
    description: 'Details of the telephone numbers used to contact organizations, services, and locations.'
    properties:
      id:
        description: 'Each entry must have a unique identifier.'
        type: string
      location_id:
        description: 'The identifier of the location where this phone number is located.'
        type: string
      service_id:
        description: 'The identifier of the service for which this is the phone number.'
        type: string
      organization_id:
        description: 'The identifier of the organisation for which this is the phone number.'
        type: string
      contact_id:
        description: 'The identifier of the contact for which this is the phone number.'
        type: string
      service_at_location_id:
        description: 'The identifier of the ‘service at location’ table entry, when this phone number is specific to a service in a particular location.'
        type: string
      number:
        description: 'The phone number.'
        type: string
      extension:
        description: 'The extension of the phone number.'
        type: string
      type:
        description: 'Whether the phone number relates to a fixed or cellular phone.'
        type: string
      department:
        description: 'The department for which this is the phone number.'
        type: string
      language:
        description: 'A comma separated list of ISO 639-1, or ISO 639-2 [language codes](available at http://www.loc.gov/standards/iso639-2/php/code_list.php) to represent the languages available from this phone service. The three-letter codes from ISO 639-2 provide greater accuracy when describing variants of languages, which may be relevant to particular communities.'
        type: string
      description:
        description: 'A description providing extra information about the phone service (e.g. any special arrangements for accessing, or details of availability at particular times.'
        type: string
    required:
      - id
      - number      
  required_document:
    description: 'Details of any documents that are required in order to access or use services.'
    properties:
      id:
        description: 'Each document must have a unique identifier.'
        type: string
      service_id:
        description: 'The identifier of the service for which this entry describes the required document.'
        type: string
      document:
        description: 'The document required to apply for or receive the service. e.g. Government-issued ID, EU Passport.'
        type: string
    required:
      - id      
  service_area:
    description: 'Details of the geographic area for which a service is available.'
    properties:
      id:
        description: 'Each service area must have a unique identifier.'
        type: string
      service_id:
        description: 'The identifier of the service for which this entry describes the service area.'
        type: string
      service_area:
        description: 'The geographic area where a service is available. This is a free-text description, and so may be precise or indefinite as necessary.'
        type: string
      description:
        description: 'A more detailed description of this service area. Used to provide any additional information that cannot be communicated using the structured area and geometry fields.'
        type: string
    required:
      - id      
  accessibility_for_disabilities:
    description: 'Details of the arrangements for access to locations for people who have disabilities'
    properties:
      id:
        description: 'Each entry must have a unique identifier.'
        type: string
      location_id:
        description: 'The identifier of the location for which the entry describes the accessibility provision.'
        type: string
      accessibility:
        description: 'Description of assistance or infrastructure that facilitate access to clients with disabilities.'
        type: string
      details:
        description: 'Any further details relating to the relevant accessibility arrangements at this location. E.g. whether advance notice is required to use an accessibility facility.'
        type: string
    required:
      - id