qa 2.1.1 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 044adb0de6665c9ba6499467e7f91687ae42d0bf
-  data.tar.gz: 4e214ad816b495b55f3a7a9d2c9d305ac5ceef79
+SHA256:
+  metadata.gz: fb238fb83dfeddf175de6e3b39f7cbfd8bc8d665ef07bfbd68d540ca9d19541b
+  data.tar.gz: 5a3b16d8b57dff5b3ece7fbd5dfa99be1d87879675d5e6d6764782087b2b06f4
 SHA512:
-  metadata.gz: 14c63d1a98211821bd3b2e935237140f4204d71572c8748e97d1fcdef5dd95c38e0fa6d6108839f242704c705fe232095b3a923ccce12d9d49c1a7bc7001eb76
-  data.tar.gz: ebd6d89c1eb12fb9119f9f24323df221bdfe33cbaae070290dd530612869eb83b23d2efa899577a302ad3bbc6223417623a7c3862b59e808cf7fde5f828200c9
+  metadata.gz: 61d883f7a50e76e1aa0ea9d410d4251b294b81eb46355c8340af70e263ea9dddbd0f1f2407eff42dbb5ce1e04e4d04e8cb0f889a493c96885f70ea24b2a58c21
+  data.tar.gz: f0481a189b24f742f5d1c38f2c2e3c478c1cd06b427fe7cd86604b5378c64ec601f90b41af3f9ceb1c4d4d69b672cc9e957e4f08423b74664e4151663b8200f1

data/README.md

@@ -313,7 +313,7 @@ This will create two tables/models Qa::LocalAuthority and Qa::LocalAuthorityEntr
                                    label: 'Uighur',
                                    uri: 'http://id.loc.gov/vocabulary/languages/uig')
 
-Unfortunately, Rails doesn't have a mechnism for adding functional indexes to tables, so if you have a lot of rows, you'll want to add an index:
+Unfortunately, Rails doesn't have a mechanism for adding functional indexes to tables, so if you have a lot of rows, you'll want to add an index:
 
     CREATE INDEX "index_qa_local_authority_entries_on_lower_label" ON
       "qa_local_authority_entries" (local_authority_id, lower(label))
@@ -340,7 +340,7 @@ The entire list (up to the first 1000 terms) can also be returned using:
 
 #### Loading RDF data into database tables
 
- You can use the Qa::Services::RDFAuthorityParser to import rdf files into yopur database tables.  See the class file, lib/qa/services/rdf_authority_parser.rb, for examples and more information.
+ You can use the Qa::Services::RDFAuthorityParser to import rdf files into your database tables.  See the class file, lib/qa/services/rdf_authority_parser.rb, for examples and more information.
  To run the class in your local project you must include `gem 'linkeddata'` into your Gemfile and `require 'linkeddata'` into an initializer or your application.rb
 
 ### Medical Subject Headings (MeSH)
@@ -358,7 +358,7 @@ Then, create the tables in your database
 
     rake db:migrate
 
-Now that you've setup your application to use MeSH terms, you'll now need to load the tems into your
+Now that you've setup your application to use MeSH terms, you'll now need to load the terms into your
 database so you can query them locally.
 
 To import the mesh terms into the local database, first download the MeSH descriptor dump in ASCII
@@ -625,7 +625,26 @@ NOTE: All predicates with the URI as the subject will be included under "predica
 
 See [Using with autocomplete in Sufia](https://github.com/samvera/questioning_authority/wiki/Using-with-autocomplete-in-Sufia) in the wiki documentation for QA.
 
+If you are using jQueryUI >= 1.8 you can use the [autocomplete function](http://api.jqueryui.com/autocomplete/), for example:
 
+```
+  $(function(){
+    $('#some_input').autocomplete({
+      source: function (request, response) {
+        $.ajax({
+          url: "/qa/search/loc/subjects?q=" + request.term,
+          type: 'GET',
+          dataType: 'json',
+          complete: function (xhr, status) {
+            var results = $.parseJSON(xhr.responseText);
+            response(results);
+          }
+        });
+      },
+      autoFocus: true
+    });
+  });
+```
 
 # Developer Notes
 

data/app/controllers/qa/application_controller.rb

@@ -1,5 +1,7 @@
 module Qa
   class ApplicationController < ActionController::Base
+    skip_before_action :verify_authenticity_token, only: :options, raise: false
+
     # Process the OPTIONS method for all routes
     # @see route definitions in /config/routes.rb
     # @note Reference: https://fetch.spec.whatwg.org/#http-access-control-allow-headers

data/app/controllers/qa/linked_data_terms_controller.rb

@@ -2,9 +2,11 @@
 # out which linked data authority to query based on the 'vocab' param.
 
 class Qa::LinkedDataTermsController < ::ApplicationController
-  before_action :check_authority, :init_authority
+  before_action :check_authority, :init_authority, except: [:list, :reload]
   before_action :check_search_subauthority, :check_query_param, only: :search
   before_action :check_show_subauthority, :check_id_param, only: :show
+  before_action :check_uri_param, only: :fetch
+  before_action :validate_auth_reload_token, only: :reload
 
   delegate :cors_allow_origin_header, to: Qa::ApplicationController
 
@@ -14,54 +16,85 @@ class Qa::LinkedDataTermsController < ::ApplicationController
     head :not_found
   end
 
+  # Return a list of supported authority names
+  # get "/list/linked_data/authorities"
+  # @see Qa::Authorities::LinkedData::AuthorityService#authority_names
+  def list
+    render json: Qa::Authorities::LinkedData::AuthorityService.authority_names.to_json
+  end
+
+  # Reload authority configurations
+  # get "/reload/linked_data/authorities?auth_token=YOUR_AUTH_TOKEN_DEFINED_HERE"
+  # @see Qa::Authorities::LinkedData::AuthorityService#load_authorities
+  def reload
+    Qa::Authorities::LinkedData::AuthorityService.load_authorities
+    list
+  end
+
   # Return a list of terms based on a query
+  # get "/search/linked_data/:vocab(/:subauthority)"
   # @see Qa::Authorities::LinkedData::SearchQuery#search
-  def search # rubocop:disable Metrics/MethodLength
-    begin
-      terms = @authority.search(query, subauth: subauthority, language: language, replacements: replacement_params)
-    rescue Qa::ServiceUnavailable
-      logger.warn "Service Unavailable - Search query #{query} unsuccessful for#{subauth_warn_msg} authority #{vocab_param}"
-      head :service_unavailable
-      return
-    rescue Qa::ServiceError
-      logger.warn "Internal Server Error - Search query #{query} unsuccessful for#{subauth_warn_msg} authority #{vocab_param}"
-      head :internal_server_error
-      return
-    rescue RDF::FormatError
-      logger.warn "RDF Format Error - Results from search query #{query} for#{subauth_warn_msg} authority #{vocab_param} " \
-                  "was not identified as a valid RDF format.  You may need to include the linkeddata gem."
-      head :internal_server_error
-      return
-    end
+  def search
+    terms = @authority.search(query, subauth: subauthority, language: language, replacements: replacement_params)
     cors_allow_origin_header(response)
     render json: terms
+  rescue Qa::ServiceUnavailable
+    logger.warn "Service Unavailable - Search query #{query} unsuccessful for#{subauth_warn_msg} authority #{vocab_param}"
+    head :service_unavailable
+  rescue Qa::ServiceError
+    logger.warn "Internal Server Error - Search query #{query} unsuccessful for#{subauth_warn_msg} authority #{vocab_param}"
+    head :internal_server_error
+  rescue RDF::FormatError
+    logger.warn "RDF Format Error - Results from search query #{query} for#{subauth_warn_msg} authority #{vocab_param} " \
+                "was not identified as a valid RDF format.  You may need to include the linkeddata gem."
+    head :internal_server_error
   end
 
-  # Return all the information for a given term
+  # Return all the information for a given term given an id or URI
+  # get "/show/linked_data/:vocab/:id"
+  # get "/show/linked_data/:vocab/:subauthority/:id
   # @see Qa::Authorities::LinkedData::FindTerm#find
   def show # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
-    begin
-      term = @authority.find(id, subauth: subauthority, language: language, replacements: replacement_params)
-    rescue Qa::TermNotFound
-      logger.warn "Term Not Found - Fetch term #{id} unsuccessful for#{subauth_warn_msg} authority #{vocab_param}"
-      head :not_found
-      return
-    rescue Qa::ServiceUnavailable
-      logger.warn "Service Unavailable - Fetch term #{id} unsuccessful for#{subauth_warn_msg} authority #{vocab_param}"
-      head :service_unavailable
-      return
-    rescue Qa::ServiceError
-      logger.warn "Internal Server Error - Fetch term #{id} unsuccessful for#{subauth_warn_msg} authority #{vocab_param}"
-      head :internal_server_error
-      return
-    rescue RDF::FormatError
-      logger.warn "RDF Format Error - Results from fetch term #{id} for#{subauth_warn_msg} authority #{vocab_param} " \
-                  "was not identified as a valid RDF format.  You may need to include the linkeddata gem."
-      head :internal_server_error
-      return
-    end
+    term = @authority.find(id, subauth: subauthority, language: language, replacements: replacement_params, jsonld: jsonld?)
+    cors_allow_origin_header(response)
+    content_type = jsonld? ? 'application/ld+json' : 'application/json'
+    render json: term, content_type: content_type
+  rescue Qa::TermNotFound
+    logger.warn "Term Not Found - Fetch term #{id} unsuccessful for#{subauth_warn_msg} authority #{vocab_param}"
+    head :not_found
+  rescue Qa::ServiceUnavailable
+    logger.warn "Service Unavailable - Fetch term #{id} unsuccessful for#{subauth_warn_msg} authority #{vocab_param}"
+    head :service_unavailable
+  rescue Qa::ServiceError
+    logger.warn "Internal Server Error - Fetch term #{id} unsuccessful for#{subauth_warn_msg} authority #{vocab_param}"
+    head :internal_server_error
+  rescue RDF::FormatError
+    logger.warn "RDF Format Error - Results from fetch term #{id} for#{subauth_warn_msg} authority #{vocab_param} " \
+                "was not identified as a valid RDF format.  You may need to include the linkeddata gem."
+    head :internal_server_error
+  end
+
+  # Return all the information for a given term given a URI
+  # get "/fetch/linked_data/:vocab"
+  # @see Qa::Authorities::LinkedData::FindTerm#find
+  def fetch # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+    term = @authority.find(uri, subauth: subauthority, language: language, replacements: replacement_params, jsonld: jsonld?)
     cors_allow_origin_header(response)
-    render json: term
+    content_type = jsonld? ? 'application/ld+json' : 'application/json'
+    render json: term, content_type: content_type
+  rescue Qa::TermNotFound
+    logger.warn "Term Not Found - Fetch term #{uri} unsuccessful for#{subauth_warn_msg} authority #{vocab_param}"
+    head :not_found
+  rescue Qa::ServiceUnavailable
+    logger.warn "Service Unavailable - Fetch term #{uri} unsuccessful for#{subauth_warn_msg} authority #{vocab_param}"
+    head :service_unavailable
+  rescue Qa::ServiceError
+    logger.warn "Internal Server Error - Fetch term #{uri} unsuccessful for#{subauth_warn_msg} authority #{vocab_param}"
+    head :internal_server_error
+  rescue RDF::FormatError
+    logger.warn "RDF Format Error - Results from fetch term #{uri} for#{subauth_warn_msg} authority #{vocab_param} " \
+                "was not identified as a valid RDF format.  You may need to include the linkeddata gem."
+    head :internal_server_error
   end
 
   private
@@ -101,10 +134,20 @@ class Qa::LinkedDataTermsController < ::ApplicationController
     end
 
     def check_query_param
-      if params[:q].nil? || !params[:q].size.positive? # rubocop:disable Style/GuardClause
-        logger.warn "Required search param 'q' is missing or empty"
-        head :bad_request
-      end
+      missing_required_param('search', 'q') if params[:q].blank?
+    end
+
+    def check_id_param
+      missing_required_param('show', 'id') if id.blank?
+    end
+
+    def check_uri_param
+      missing_required_param('fetch', 'uri') if uri.blank?
+    end
+
+    def missing_required_param(action_name, param_name)
+      logger.warn "Required #{action_name} param '#{param_name}' is missing or empty"
+      head :bad_request
     end
 
     # converts wildcards into URL-encoded characters
@@ -112,11 +155,8 @@ class Qa::LinkedDataTermsController < ::ApplicationController
       params[:q].gsub("*", "%2A")
     end
 
-    def check_id_param
-      if params[:id].nil? || !params[:id].size.positive? # rubocop:disable Style/GuardClause
-        logger.warn "Required show param 'id' is missing or empty"
-        head :bad_request
-      end
+    def uri
+      params[:uri]
     end
 
     def id
@@ -138,4 +178,23 @@ class Qa::LinkedDataTermsController < ::ApplicationController
     def subauth_warn_msg
       subauthority.nil? ? "" : " sub-authority #{subauthority} in"
     end
+
+    def format
+      return 'json' unless params.key?(:format)
+      return 'json' if params[:format].blank?
+      params[:format]
+    end
+
+    def jsonld?
+      format == 'jsonld'
+    end
+
+    def validate_auth_reload_token
+      token = params.key?(:auth_token) ? params[:auth_token] : nil
+      valid = Qa.config.valid_authority_reload_token?(token)
+      return true if valid
+      logger.warn "FAIL: unable to reload authorities; error_msg: Invalid token (#{token}) does not match expected token."
+      head :unauthorized
+      false
+    end
 end

data/config/initializers/linked_data_authorities.rb

@@ -1,17 +1 @@
-auth_cfg = {}
-# load QA configured linked data authorities
-Dir[File.join(Qa::Engine.root, 'config', 'authorities', 'linked_data', '*.json')].each do |fn|
-  auth = File.basename(fn, '.json').upcase.to_sym
-  json = File.read(File.expand_path(fn, __FILE__))
-  cfg = JSON.parse(json).deep_symbolize_keys
-  auth_cfg[auth] = cfg
-end
-
-# load app configured linked data authorities and overrides
-Dir[Rails.root.join('config', 'authorities', 'linked_data', '*.json')].each do |fn|
-  auth = File.basename(fn, '.json').upcase.to_sym
-  json = File.read(File.expand_path(fn, __FILE__))
-  cfg = JSON.parse(json).deep_symbolize_keys
-  auth_cfg[auth] = cfg
-end
-LINKED_DATA_AUTHORITIES_CONFIG = auth_cfg.freeze
+Qa::Authorities::LinkedData::AuthorityService.load_authorities

data/config/routes.rb

@@ -1,5 +1,8 @@
 Qa::Engine.routes.draw do
+  get "/list/linked_data/authorities", controller: :linked_data_terms, action: :list
+  get "/reload/linked_data/authorities", controller: :linked_data_terms, action: :reload
   get "/search/linked_data/:vocab(/:subauthority)", controller: :linked_data_terms, action: :search
+  get "/fetch/linked_data/:vocab", controller: :linked_data_terms, action: :fetch
   get "/show/linked_data/:vocab/:id", controller: :linked_data_terms, action: :show
   get "/show/linked_data/:vocab/:subauthority/:id", controller: :linked_data_terms, action: :show
   get "/terms/:vocab(/:subauthority)",  controller: :terms, action: :index

data/lib/generators/qa/apidoc/USAGE

@@ -0,0 +1,11 @@
+Description:
+  This generator adds interactive documentation for the linked data API.
+
+Example:
+  rails generate qa:apidoc
+
+  This will create:
+    public/qa/apidoc/*
+
+  You can access the UI at:
+    https://YOUR_APP_HOST/qa/apidoc/

data/lib/generators/qa/apidoc/apidoc_generator.rb

@@ -0,0 +1,22 @@
+class Qa::ApidocGenerator < Rails::Generators::Base
+  source_root File.expand_path('../templates', __FILE__)
+
+  desc """
+This generator makes the following changes to your application:
+1. Add swagger-docs gem and bundle install
+2. Add swagger documentation for the QA linked data API
+
+"""
+
+  def add_to_gemfile
+    gem 'swagger-docs'
+
+    Bundler.with_clean_env do
+      run "bundle install"
+    end
+  end
+
+  def copy_api_docs
+    directory "public/qa/apidoc", recursive: false
+  end
+end

data/lib/generators/qa/apidoc/templates/public/qa/apidoc/apidoc.json

@@ -0,0 +1,1322 @@
+{
+  "openapi": "3.0.1",
+  "info": {
+    "title": "QA 2.2 Linked Data API",
+    "version": "2.2",
+    "license": {
+      "name": "Apache 2.0",
+      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
+    }
+  },
+  "servers": [
+    {
+      "url": "http://{site_host}/{apiBase}",
+      "description": "QA v2.2 API Server",
+      "variables": {
+        "site_host": {
+          "default": "localhost:3000",
+          "description": ""
+        },
+        "apiBase": {
+          "default": "qa"
+        }
+      }
+    }
+  ],
+  "paths": {
+    "/list/linked_data/authorities": {
+      "get": {
+        "summary": "List currently loaded linked data authorities",
+        "operationId": "GET_listAuthorities",
+        "tags": [
+          "Authority Management"
+        ],
+        "responses": {
+          "200": {
+            "description": "Successfully accessed authority and received results.",
+            "headers": {
+              "Access-Control-Allow-Origin": {
+                "description": "CORS header will be * if cors_headers_enabled",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/linked_data_authorities_list_result"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/reload/linked_data/authorities": {
+      "get": {
+        "summary": "Reload linked data authorities.  Using this command avoids having to restart the rails server.",
+        "operationId": "GET_reloadAuthorities",
+        "tags": [
+          "Authority Management"
+        ],
+        "parameters": [
+          {
+            "description": "Security token which must be included for this command to execute.",
+            "in": "query",
+            "name": "auth_token",
+            "required": true,
+            "schema": {
+              "default": "",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successfully reloaded authorities.",
+            "headers": {
+              "Access-Control-Allow-Origin": {
+                "description": "CORS header will be * if cors_headers_enabled",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/linked_data_authorities_list_result"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/search/linked_data/{vocab}": {
+      "get": {
+        "summary": "Send a query string to an authority and return search results.  Parameters are typical examples.  Actual parameters are driven by the authority's config file.",
+        "operationId": "GET_searchAuthority",
+        "tags": [
+          "Search Query"
+        ],
+        "parameters": [
+          {
+            "description": "Name of the authority's configuration file.",
+            "in": "path",
+            "name": "vocab",
+            "required": true,
+            "schema": {
+              "default": "oclc_fast",
+              "type": "string"
+            }
+          },
+          {
+            "description": "The query string",
+            "in": "query",
+            "name": "q",
+            "required": true,
+            "schema": {
+              "default": "science",
+              "type": "string"
+            }
+          },
+          {
+            "description": "Limit number of returned results. NOTE: Most authorities use maxRecords instead of maximumRecords for this parameter.",
+            "in": "query",
+            "name": "maximumRecords",
+            "required": false,
+            "schema": {
+              "default": 4,
+              "type": "integer"
+            }
+          },
+          {
+            "description": "Limit string values to this language when multiple languages are provided.",
+            "in": "query",
+            "name": "lang",
+            "required": false,
+            "schema": {
+              "default": "en",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successfully accessed authority and received results.",
+            "headers": {
+              "Access-Control-Allow-Origin": {
+                "description": "CORS header will be * if cors_headers_enabled",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/linked_data_query_results"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request - occurs when required params are missing (e.g. q)",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal Server Error - can be raised while attempting to access the external authority OR during processing of results when results are not a valid RDF Format",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Service Unavailable - can be raised while attempting to access the external authority",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          }
+        }
+      },
+      "options": {
+        "summary": "CORS preflight request",
+        "operationId": "OPTIONS_searchAuthority",
+        "tags": [
+          "Search Query"
+        ],
+        "parameters": [
+          {
+            "description": "Name of the authority's configuration file.",
+            "in": "path",
+            "name": "vocab",
+            "required": true,
+            "schema": {
+              "default": "oclc_fast",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "When CORS is enabled, perform CORS preflight for searching an authority",
+            "headers": {
+              "Access-Control-Allow-Origin": {
+                "description": "CORS header will be * if CORS headers are enabled",
+                "schema": {
+                  "type": "string"
+                }
+              },
+              "Access-Control-Allow-Methods": {
+                "description": "Indicates which method a future CORS request to the same resource might use.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "OPTIONS action is not implement when CORS headers are not enabled",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/search/linked_data/{vocab}/{subauthority}": {
+      "get": {
+        "summary": "Send a query string to a subauthority in an authority and return search results.",
+        "operationId": "GET_searchSubauthority",
+        "tags": [
+          "Search Query"
+        ],
+        "parameters": [
+          {
+            "description": "Name of the authority's configuration file.",
+            "in": "path",
+            "name": "vocab",
+            "required": true,
+            "schema": {
+              "default": "oclc_fast",
+              "type": "string"
+            }
+          },
+          {
+            "description": "Name of the subauthority.",
+            "in": "path",
+            "name": "subauthority",
+            "required": true,
+            "schema": {
+              "default": "personal_name",
+              "type": "string"
+            }
+          },
+          {
+            "description": "The query string",
+            "in": "query",
+            "name": "q",
+            "required": true,
+            "schema": {
+              "default": "twain",
+              "type": "string"
+            }
+          },
+          {
+            "description": "Limit number of returned results.  NOTE: Most authorities use maxRecords instead of maximumRecords for this parameter.",
+            "in": "query",
+            "name": "maximumRecords",
+            "required": false,
+            "schema": {
+              "default": 4,
+              "type": "integer"
+            }
+          },
+          {
+            "description": "Limit string values to this language when multiple languages are provided.",
+            "in": "query",
+            "name": "lang",
+            "required": false,
+            "schema": {
+              "default": "en",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successfully accessed subauthority in an authority and received results.",
+            "headers": {
+              "Access-Control-Allow-Origin": {
+                "description": "CORS header will be * if CORS headers are enabled",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/linked_data_query_results"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request - occurs when required params are missing (e.g. q)",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal Server Error - can be raised while attempting to access the external authority OR during processing of results when results are not a valid RDF Format",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Service Unavailable - can be raised while attempting to access the external authority",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          }
+        }
+      },
+      "options": {
+        "summary": "CORS preflight request",
+        "operationId": "OPTIONS_searchSubauthority",
+        "tags": [
+          "Search Query"
+        ],
+        "parameters": [
+          {
+            "description": "Name of the authority's configuration file.",
+            "in": "path",
+            "name": "vocab",
+            "required": true,
+            "schema": {
+              "default": "oclc_fast",
+              "type": "string"
+            }
+          },
+          {
+            "description": "Name of the subauthority.",
+            "in": "path",
+            "name": "subauthority",
+            "required": true,
+            "schema": {
+              "default": "personal_name",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Perform CORS preflight for searching a subauthoroity in an authority",
+            "headers": {
+              "Access-Control-Allow-Origin": {
+                "description": "CORS header will be * if CORS headers are enabled",
+                "schema": {
+                  "type": "string"
+                }
+              },
+              "Access-Control-Allow-Methods": {
+                "description": "Indicates which method a future CORS request to the same resource might use.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "OPTIONS action is not implement when CORS headers are not enabled",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/show/linked_data/{vocab}/{id}": {
+      "get": {
+        "operationId": "GET_fetchByIDFromAuthority",
+        "summary": "Get a single term from an authority.  Generally there are no additional parameters.  See the authority's configuration file to be sure.  Some authorities support `lang` which can be used to filter the language of returned strings.",
+        "tags": [
+          "Fetch Term"
+        ],
+        "parameters": [
+          {
+            "description": "Name of the authority's configuration file.",
+            "in": "path",
+            "name": "vocab",
+            "required": true,
+            "schema": {
+              "default": "oclc_fast",
+              "type": "string"
+            }
+          },
+          {
+            "description": "The ID or URI for the term being retrieved.",
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": {
+              "default": "1914919",
+              "type": "string"
+            }
+          },
+          {
+            "description": "The format of the returned result.",
+            "in": "query",
+            "name": "format",
+            "required": false,
+            "schema": {
+              "default": "json",
+              "type": "string",
+              "enum": [
+                "json",
+                "jsonld"
+              ]
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successfully accessed authority and received term.",
+            "headers": {
+              "Access-Control-Allow-Origin": {
+                "description": "CORS header will be * if CORS headers are enabled",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/linked_data_term_json_result"
+                }
+              },
+              "application/ld+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/linked_data_term_jsonld_result"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request - occurs when required params are missing (e.g. id)",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal Server Error - can be raised while attempting to access the external authority OR during processing of results when results are not a valid RDF Format",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Service Unavailable - can be raised while attempting to access the external authority",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          }
+        }
+      },
+      "options": {
+        "summary": "CORS preflight request",
+        "operationId": "OPTIONS_fetchFromAuthority",
+        "tags": [
+          "Fetch Term"
+        ],
+        "parameters": [
+          {
+            "description": "Name of the authority's configuration file.",
+            "in": "path",
+            "name": "vocab",
+            "required": true,
+            "schema": {
+              "default": "oclc_fast",
+              "type": "string"
+            }
+          },
+          {
+            "description": "The ID or URI for the term being retrieved.",
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": {
+              "default": "1914919",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Perform CORS preflight for fetching a term from an authority",
+            "headers": {
+              "Access-Control-Allow-Origin": {
+                "description": "CORS header will be * if CORS headers are enabled",
+                "schema": {
+                  "type": "string"
+                }
+              },
+              "Access-Control-Allow-Methods": {
+                "description": "Indicates which method a future CORS request to the same resource might use.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "OPTIONS action is not implement when CORS headers are not enabled",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/show/linked_data/{vocab}/{subauthority}/{id}": {
+      "get": {
+        "operationId": "GET_fetchByIDFromSubauthority",
+        "summary": "Get a single term from a subauthority in an authority.  Generally there are no additional parameters.  See the authority's configuration file to be sure.  Some authorities support `lang` which can be used to filter the language of returned strings.",
+        "tags": [
+          "Fetch Term"
+        ],
+        "parameters": [
+          {
+            "description": "Name of the authority's configuration file.",
+            "in": "path",
+            "name": "vocab",
+            "required": true,
+            "schema": {
+              "default": "loc",
+              "type": "string"
+            }
+          },
+          {
+            "description": "Name of the subauthority.",
+            "in": "path",
+            "name": "subauthority",
+            "required": true,
+            "schema": {
+              "default": "names",
+              "type": "string"
+            }
+          },
+          {
+            "description": "The ID or URI for the term being retrieved.",
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": {
+              "default": "n92016188",
+              "type": "string"
+            }
+          },
+          {
+            "description": "The format of the returned result.",
+            "in": "query",
+            "name": "format",
+            "required": false,
+            "schema": {
+              "default": "json",
+              "type": "string",
+              "enum": [
+                "json",
+                "jsonld"
+              ]
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successfully accessed subauthority in the authority and received term.",
+            "headers": {
+              "Access-Control-Allow-Origin": {
+                "description": "CORS header will be * if CORS headers are enabled",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/linked_data_term_json_result"
+                }
+              },
+              "application/ld+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/linked_data_term_jsonld_result"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request - occurs when required params are missing (e.g. id)",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal Server Error - can be raised while attempting to access the external authority OR during processing of results when results are not a valid RDF Format",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Service Unavailable - can be raised while attempting to access the external authority",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          }
+        }
+      },
+      "options": {
+        "summary": "CORS preflight request",
+        "operationId": "OPTIONS_fetchFromSubauthority",
+        "tags": [
+          "Fetch Term"
+        ],
+        "parameters": [
+          {
+            "description": "Name of the authority's configuration file.",
+            "in": "path",
+            "name": "vocab",
+            "required": true,
+            "schema": {
+              "default": "loc",
+              "type": "string"
+            }
+          },
+          {
+            "description": "Name of the subauthority.",
+            "in": "path",
+            "name": "subauthority",
+            "required": true,
+            "schema": {
+              "default": "names",
+              "type": "string"
+            }
+          },
+          {
+            "description": "The ID or URI for the term being retrieved.",
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": {
+              "default": "n92016188",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Perform CORS preflight for fetching a term from a subauthority in an authority",
+            "headers": {
+              "Access-Control-Allow-Origin": {
+                "description": "CORS header will be * if CORS headers are enabled",
+                "schema": {
+                  "type": "string"
+                }
+              },
+              "Access-Control-Allow-Methods": {
+                "description": "Indicates which method a future CORS request to the same resource might use.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "OPTIONS action is not implement when CORS headers are not enabled",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/fetch/linked_data/{vocab}": {
+      "get": {
+        "operationId": "GET_fetchURIFromAuthority",
+        "summary": "Get a single term from an authority given the term's URI.  Generally there are no additional parameters.  See the authority's configuration file to be sure.  Some authorities support `lang` which can be used to filter the language of returned strings.  NOTE: The authorities provided with QA do not support fetch by URI.  See more authority configs at: https://github.com/LD4P/linked_data_authorities",
+        "tags": [
+          "Fetch Term"
+        ],
+        "parameters": [
+          {
+            "description": "Name of the authority's configuration file.",
+            "in": "path",
+            "name": "vocab",
+            "required": true,
+            "schema": {
+              "default": "loc",
+              "type": "string"
+            }
+          },
+          {
+            "description": "The URI for the term being retrieved.",
+            "in": "query",
+            "name": "uri",
+            "required": true,
+            "schema": {
+              "default": "http://id.loc.gov/authorities/genreForms/gf2011026141",
+              "type": "string"
+            }
+          },
+          {
+            "description": "The format of the returned result.",
+            "in": "query",
+            "name": "format",
+            "required": false,
+            "schema": {
+              "default": "json",
+              "type": "string",
+              "enum": [
+                "json",
+                "jsonld"
+              ]
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successfully accessed authority and received term.",
+            "headers": {
+              "Access-Control-Allow-Origin": {
+                "description": "CORS header will be * if CORS headers are enabled",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/linked_data_term_json_result"
+                }
+              },
+              "application/ld+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/linked_data_term_jsonld_result"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request - occurs when required params are missing (e.g. uri)",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal Server Error - can be raised while attempting to access the external authority OR during processing of results when results are not a valid RDF Format",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Service Unavailable - can be raised while attempting to access the external authority",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          }
+        }
+      },
+      "options": {
+        "summary": "CORS preflight request",
+        "operationId": "OPTIONS_fetchFromAuthority",
+        "tags": [
+          "Fetch Term"
+        ],
+        "parameters": [
+          {
+            "description": "Name of the authority's configuration file.",
+            "in": "path",
+            "name": "vocab",
+            "required": true,
+            "schema": {
+              "default": "loc",
+              "type": "string"
+            }
+          },
+          {
+            "description": "The ID or URI for the term being retrieved.",
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": {
+              "default": "http://id.loc.gov/authorities/genreForms/gf2011026141",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Perform CORS preflight for fetching a term from an authority",
+            "headers": {
+              "Access-Control-Allow-Origin": {
+                "description": "CORS header will be * if CORS headers are enabled",
+                "schema": {
+                  "type": "string"
+                }
+              },
+              "Access-Control-Allow-Methods": {
+                "description": "Indicates which method a future CORS request to the same resource might use.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "OPTIONS action is not implement when CORS headers are not enabled",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/fetch/linked_data/{vocab}/{subauthority}": {
+      "get": {
+        "operationId": "GET_fetchByURIFromSubauthority",
+        "summary": "Get a single term from a subauthority in an authority given the term's URI.  Generally there are no additional parameters.  See the authority's configuration file to be sure.  Some authorities support `lang` which can be used to filter the language of returned strings.  NOTE: There currently aren't any authorities configured that support subauthorities and access terms using a URI instead of an ID.  The default values in this example show what you might see but DO NOT WORK with the current LOC config.",
+        "tags": [
+          "Fetch Term"
+        ],
+        "parameters": [
+          {
+            "description": "Name of the authority's configuration file.",
+            "in": "path",
+            "name": "vocab",
+            "required": true,
+            "schema": {
+              "default": "loc",
+              "type": "string"
+            }
+          },
+          {
+            "description": "Name of the subauthority.",
+            "in": "path",
+            "name": "subauthority",
+            "required": true,
+            "schema": {
+              "default": "names",
+              "type": "string"
+            }
+          },
+          {
+            "description": "The URI for the term being retrieved.",
+            "in": "query",
+            "name": "uri",
+            "required": true,
+            "schema": {
+              "default": "http://id.loc.gov/authorities/names/n92016188",
+              "type": "string"
+            }
+          },
+          {
+            "description": "The format of the returned result.",
+            "in": "query",
+            "name": "format",
+            "required": false,
+            "schema": {
+              "default": "json",
+              "type": "string",
+              "enum": [
+                "json",
+                "jsonld"
+              ]
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successfully accessed subauthority in the authority and received term.",
+            "headers": {
+              "Access-Control-Allow-Origin": {
+                "description": "CORS header will be * if CORS headers are enabled",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/linked_data_term_json_result"
+                }
+              },
+              "application/ld+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/linked_data_term_jsonld_result"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request - occurs when required params are missing (e.g. uri)",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal Server Error - can be raised while attempting to access the external authority OR during processing of results when results are not a valid RDF Format",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Service Unavailable - can be raised while attempting to access the external authority",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          }
+        }
+      },
+      "options": {
+        "summary": "CORS preflight request",
+        "operationId": "OPTIONS_fetchFromSubauthority",
+        "tags": [
+          "Fetch Term"
+        ],
+        "parameters": [
+          {
+            "description": "Name of the authority's configuration file.",
+            "in": "path",
+            "name": "vocab",
+            "required": true,
+            "schema": {
+              "default": "loc",
+              "type": "string"
+            }
+          },
+          {
+            "description": "Name of the subauthority.",
+            "in": "path",
+            "name": "subauthority",
+            "required": true,
+            "schema": {
+              "default": "names",
+              "type": "string"
+            }
+          },
+          {
+            "description": "The URI for the term being retrieved.",
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": {
+              "default": "http://id.loc.gov/authorities/names/n92016188",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Perform CORS preflight for fetching a term from a subauthority in an authority",
+            "headers": {
+              "Access-Control-Allow-Origin": {
+                "description": "CORS header will be * if CORS headers are enabled",
+                "schema": {
+                  "type": "string"
+                }
+              },
+              "Access-Control-Allow-Methods": {
+                "description": "Indicates which method a future CORS request to the same resource might use.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "OPTIONS action is not implement when CORS headers are not enabled",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "example": ""
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "linked_data_authorities_list_result": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      },
+      "linked_data_query_results": {
+        "type": "array",
+        "items": {
+          "required": [
+            "id",
+            "uri",
+            "label"
+          ],
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "uri": {
+              "type": "string"
+            },
+            "label": {
+              "type": "string"
+            },
+            "context": {
+              "type": "object"
+            }
+          }
+        }
+      },
+      "linked_data_term_json_result": {
+        "required": [
+          "id",
+          "uri",
+          "label"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "uri": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "altlabel": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "broader": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "narrower": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "sameas": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "predicates": {
+            "type": "object",
+          }
+        }
+      },
+      "linked_data_term_jsonld_result": {
+        "required": [
+          "@context",
+          "@graph"
+        ],
+        "properties": {
+          "@context": {
+            "type": "object"
+          },
+          "@graph": {
+            "type": "object"
+          }
+        }
+      }
+    }
+  },
+  "tags": [
+    {
+      "name": "Authority Management",
+      "description": "Services managing all authorities."
+    },
+    {
+      "name": "Search Query",
+      "description": "Services sending a search query to an authority to retrieve multiple results."
+    },
+    {
+      "name": "Fetch Term",
+      "description": "Services to fetch a single term from an authority."
+    }
+  ]
+}