Releases: samvera/questioning_authority
v4.2.2
Change Log
Patch release with bug fixes only...
- bug fix to correctly set the content-type in the header to text/n3 for discogs authority
Actions Required to Upgrade
There are no required actions for this upgrade other than adjusting your gem file to allow for version 4.2.2 to be included by bundler.
v4.2.1
Actions Required to Upgrade
There are no required actions for this upgrade other than adjusting your gem file to allow for version 4.2.1 to be included by bundler.
Updates
Linked Data - single term return format
Previously, linked data for a single term could be returned as normalized json or json-ld. It can now also be returned as n3.
JSON: http://localhost:3000/qa/show/linked_data/oclc_fast/1364193
JSON: http://localhost:3000/qa/show/linked_data/oclc_fast/1364193?format=json
JSON-LD: http://localhost:3000/qa/show/linked_data/oclc_fast/1364193?format=jsonld
N3: http://localhost:3000/qa/show/linked_data/oclc_fast/1364193?format=n3
Bug Fixes
Improved error handling
Errors occurring while reading in a linked data graph are parsed to get the error code to allow for more precise reporting of errors that occur. This process did not always succeed in parsing the error code from the error message. It has been adjusted to be more flexible and thus able to parse more error messages correctly.
Getty TGN returning wrong data
Getty TGN was configured to return ULAN data instead of TGN. This has been fixed.
Change Log
- add ability to return a single term as n3 format for linked data
- allow error from RDF::Graph to be parsed with or without parentheses around
- remove CircleCI ruby/rails version defaults (maintenance)
- adjust queries for TGN to use TGN scheme and not ULAN
v4.2.0
Actions Required to Upgrade
There are no required actions for this upgrade other than adjusting your gem file to allow for version 4.2.0 to be included by bundler.
Optional Upgrade Actions
Linked Data - Property Maps - Optional config
This applies to search queries for linked data authorities that define extended context. Without extended context, an authority will return search results with the basic information (i.e. uri, id, label). An authority can have extended context configured that returns additional information with each search result.
Prior to this release, all configured extended context was included in the search results even if the extended context property did not have values in the results graph.
Starting with release 4.2.0, when a property map has optional=false either by being configured directly or by inheriting the default configuration, the results will be the same as the old behavior. That is, the property will be included in the results regardless of whether or not the property has values in the graph for an entity.
Example: Pre 4.2.0 behavior AND 4.2.0 behavior when optional=false. Results include Affiliation when it has no values.
{
"uri": "http://id.loc.gov/rwo/agents/n79021164"
"id": "n 79021164"
"label": "Twain, Mark, 1835-1910"
"context": [
{
"property": "Descriptor",
"values": ["Americans"],
"selectable": false,
"drillable": false
},
{
"property": "Affiliation",
"values": [],
"selectable": false,
"drillable": false
}
]
}
When a property map has optional=true either by being configured directly or by inheriting the default configuration, the property will only be included in the results if it has a value.
Example: 4.2.0 behavior when optional=true. Results exclude Affiliation when it has no values.
{
"uri": "http://id.loc.gov/rwo/agents/n79021164"
"id": "n 79021164"
"label": "Twain, Mark, 1835-1910"
"context": [
{
"property": "Descriptor",
"values": ["Americans"],
"selectable": false,
"drillable": false
}
]
}
Per property configuration
To directly configure for a specific property, add the optional parameter to the property map in the authority configuration file (e.g. config/authorities/linked_data/oclc_fast.json).
{
"term": { ... }
"search": {
"url": { ... }
"qa_replacement_pattern": { ... }
"results": { ... }
"context": {
"properties": [
{
"property_label_default": "Descriptor",
"property_label_i18n": "qa.linked_data.authority.locnames_ld4l_cache.type_label",
"ldpath": "madsrdf:entityDescriptor/madsrdf:authoritativeLabel :: xsd:string",
"optional": false
},
{
"property_label_default": "Affiliation",
"property_label_i18n": "qa.linked_data.authority.locnames_ld4l_cache.field_of_activity",
"ldpath": "(madsrdf:hasAffiliation/madsrdf:organization/skos:prefLabel) | (madsrdf:hasAffiliation/madsrdf:organization/rds:label) :: xsd:string",
"optional": true
}
]
}
}
}
NOTE: If optional is not specified for a property, it will inherit the configured default value.
Configuring a default
QA will use a default value of "optional": false if no change is made to the default configuration. This maintains backward compatibility.
To change the configuration of the default to true:
- Edit /config/initializers/qa.rb
- If this file doesn't exist in your app, you can copy it from /lib/generators/qa/install/templates/config/initializers/qa.rb
- If it exists from an earlier release, you can copy in the new configs by comparing your version of the file to the generator version.
- Uncomment and set the value of
config.property_map_default_for_optional.- If true, excludes properties with blank values. Applies to properties that have not overridden this default in the authority configuration file.
- If false, includes properties with blank values. Applies to properties that have not overridden this default in the authority configuration file.
config.property_map_default_for_optional = true # initially set to false; set to true to hide properties without values
New subauthority for LOC linked data authority
The LOC linked data authority now supports the music_performance subauthority which is used to fetch terms from LC Medium of Performance Thesaurus for Music (LCMPT).
http://localhost:3000/qa/show/linked_data/loc/music_performance/mp2013015171
Special Processing for LOC IDs in linked data module
This section is information only. No action is required.
The linked data module can receive an ID and transform it into a URI. At this time, many, but not all, LOC IDs have a blank in the ID (e.g. 'n 79021164'). The associated URI does not have a blank (e.g. 'http://id.loc.gov/rwo/agents/n79021164').
Special processing was put in place in this release to check if the authority being processed accesses http://id.loc.gov. If it does and the first attempt to transform the ID into a URI fails, it will remove the from the ID and try again.
A similar process is used to extract the ID from the URI by making a second attempt after adding a between the initial letters and the start of the numbers.
Change Log
- allow property_map.optional? default value to be configurable
- make it optional whether to include blank values in linked data extended context
- allow id to be identified by multiple predicates/paths
- add music performance to loc linked data config
- improve comments about LOC special processing
- add bytes and bytes/s to performance data
- raise an exception if data can’t be normalized
- determine if loc special processing is needed based on template uri instead of authority name
- removing the test configuration for using Rails 5.0.x releases
- updates the CircleCI configuration to test against Rails releases 5.2.3, 5.1.7, and 5.0.7.2
- updates the CircleCI configuration to test against Ruby releases 2.6.3, 2.5.5, and 2.4.6
v4.1.1
Change Log
Patch release with bug fixes only...
- special processing for LOC IDs
- reset uri with every call to find
- do not discard blank nodes when filtering graph (ignored during mapping)
- improve deprecation warnings
Actions Required to Upgrade
There are no required actions for this upgrade other than adjusting your gem file to allow for version 4.1.1 to be included by bundler.
v4.1.0
Actions Required to Upgrade
There are no required actions for this upgrade other than adjusting your gem file to allow for version 4.1.0 to be included by bundler. There are a few recommended steps that apply only if you are accessing linked data authorities. See the New Features section for details.
New Authority
NEW Discogs authority
This is optional and no action is required.
Action is required only if you want to use the Discogs authority. See Connecting to Discogs for usage information on the new Discogs Authority (music database).
New Features
Force ldpath to only use passed context graph
This is recommended, but not required. Action recommended if you access linked data authorities.
The ldpath gem is used to extract primary results and extended context from the results graph. If not told to only use the passed in graph, ldpath will potentially perform multiple network calls for each search result to gather the specificed extended context. This can deteriorate the performance of a search query. It is recommended that the ability to look outside the passed in graph be turned off, and it is off by default.
To configure ldpath's access to external data:
- Edit
/config/initializers/qa.rb- If this file doesn't exist in your app, you can copy it from /lib/generators/qa/install/templates/config/initializers/qa.rb
- If it exists from an earlier release, you can copy in the new configs by comparing your version of the file to the generator version.
- Uncomment and set the value of
config.limit_ldpath_to_context. If true, ldpath will not do any additional network calls and will only extract values from the passed in graph (default). If false, ldpath may make additional network calls in an attempt to resolve requested values.
Deprecation of results predicates -- use ldpaths instead:
This is recommended, but not required. Action recommended if you access linked data authorities to avoid deprecation warnings.
For linked data configurations, defining results to extract using predicates is deprecated. Identify results to extract with ldpaths instead.
To address the deprecations, modify all linked data authorities defined in your app at config/authorities/linked_data. Edit the results: section of both search and term. Change predicates to ldpaths. Update the prefixes: section as needed.
Example:
BEFORE
{
"term": {
...
"results": {
"id_predicate": "http://purl.org/dc/terms/identifier",
"label_predicate": "http://www.w3.org/2004/02/skos/core#prefLabel",
"altlabel_predicate": "http://www.w3.org/2004/02/skos/core#altLabel",
"sameas_predicate": "http://schema.org/sameAs"
}
}
...
}
AFTER
{
"prefixes": {
"dcterms": "http://purl.org/dc/terms/",
"skos": "http://www.w3.org/2004/02/skos/core#",
"schema": "http://schema.org/"
},
"term": {
...
"results": {
"id_ldpath": "dcterms:identifier",
"label_ldpath": "skos:prefLabel",
"altlabel_ldpath": "skos:altLabel",
"sameas_ldpath": "schema:sameAs"
}
}
...
}
A similar change needs to be made to "search": -> "results":.
Language support for linked data requests
This is optional and no action is required.
The linked data processing module has language support. Documentation: Language processing in Linked Data authorities
New in this release is the ability to pass the desired language in the http accept_language header and the ability to set a site wide language preference that is used when the language is not specified another way.
To configure the site wide default:
- Edit
/config/initializers/qa.rb- If this file doesn't exist in your app, you can copy it from /lib/generators/qa/install/templates/config/initializers/qa.rb
- If it exists from an earlier release, you can copy in the new configs by comparing your version of the file to the generator version.
- Uncomment and set the value of
config.default_languageBy default, this is set to:en. If you want the default to be:en, then you do not need to take any action.
To use optional performance statistics for linked data requests
This is optional and no action is required.
To get results without performance data, either set performance_data=false or do not include the parameter on the request.
http://localhost:3000/qa/search/linked_data/oclc_fast?q=sam%20taylor&maximumRecords=1
[
{
"uri":"http://id.worldcat.org/fast/488963",
"id":"488963",
"label":"Taylor, Samuel, 1872-1958"
}
]
To include performance data, append performance_data=true to the end of search query and term fetch requests.
{
"performance":{
"result_count":1,
"fetch_time_s":0.1253,
"normalization_time_s":0.122574,
"total_time_s":0.24787399999999998
},
"results":[
{
"uri":"http://id.worldcat.org/fast/488963",
"id":"488963",
"label":"Taylor, Samuel, 1872-1958"
}
]
}
To use optional details listing of loaded linked data authorities
This is optional and no action is required.
To view the list of linked data authorities without details, either set details=false or do not include the parameter on the request.
http://localhost:3000/qa/list/linked_data/authorities
[
"LOC",
"OCLC_FAST"
]
To view the list of linked data authorities and subauthorities, append performance_data=true to the end authority list request request.
http://localhost:3000/qa/list/linked_data/authorities?details=true
[
{
label: "loc term (QA)",
uri: "urn:qa:term:loc",
authority: "loc",
action: "term"
},
{
"label":"oclc_fast search topic (QA)",
"uri":"urn:qa:search:oclc_fast:topic",
"authority":"oclc_fast",
"subauthority":"topic",
"action":"search",
"language":["en"]
},
{
"label":"oclc_fast search geographic (QA)",
"uri":"urn:qa:search:oclc_fast:geographic",
"authority":"oclc_fast",
"subauthority":"geographic",
"action":"search",
"language":["en"]
},
{
"label":"oclc_fast search event_name (QA)",
"uri":"urn:qa:search:oclc_fast:event_name",
"authority":"oclc_fast",
"subauthority":"event_name",
"action":"search",
"language":["en"]
},
{
"label":"oclc_fast search personal_name (QA)",
"uri":"urn:qa:search:oclc_fast:personal_name",
"authority":"oclc_fast",
"subauthority":"personal_name",
"action":"search",
"language":["en"]
},
{
"label":"oclc_fast search corporate_name (QA)",
"uri":"urn:qa:search:oclc_fast:corporate_name",
"authority":"oclc_fast",
"subauthority":"corporate_name",
"action":"search",
"language":["en"]
},
{
"label":"oclc_fast search uniform_title (QA)",
"uri":"urn:qa:search:oclc_fast:uniform_title",
"authority":"oclc_fast",
"subauthority":"uniform_title",
"action":"search",
"language":["en"]
},
{
"label":"oclc_fast search period (QA)",
"uri":"urn:qa:search:oclc_fast:period",
"authority":"oclc_fast",
"subauthority":"period",
"action":"search",
"language":["en"]
},
{
"label":"oclc_fast search form (QA)",
"uri":"urn:qa:search:oclc_fast:form",
"authority":"oclc_fast",
"subauthority":"form",
"action":"search",
"language":["en"]
},
{
"label":"oclc_fast search alt_lc (QA)",
"uri":"urn:qa:search:oclc_fast:alt_lc",
"authority":"oclc_fast",
"subauthority":"alt_lc",
"action":"search",
"language":["en"]
},
{
"label":"oclc_fast term (QA)",
"uri":"urn:qa:term:oclc_fast",
"authority":"oclc_fast",
"action":"term",
"language":["en"]
}
]
Change Log
- add option to include performance statistics in the returned result for linked data search query and term fetch
- add option to include authority details when getting list of linked data authorities
- add support for main results to be specified as ldpath or predicate (one or the other, not mixed)
- add Discogs authority
- allow language for linked data processing to be specified in the http accept_language header
- Remove support of Rails 5.0
- Add CircleCI Support
v4.0.0
Change Log
- refactor much of the structure of the linked data module
- refactor language processing of linked data results
- add extended context to linked data search results
- fix processing of IriTemplate mapping expansion
- add versioning to linked data configurations
- deprecate linked data config version 1.0
- update LOC and OCLCFAST linked data configs to config version 2.0
- update URL for fetching a single term from Getty through the non-linked data module
- catch and log Getty response errors
- provide better error messages with json error returned instead of empty results
- replace deprecated URI.escape with ERB::Util.url_encode
- put mesh task in the qa namespace
- remove older deprecated code
- move documentation from the README to the wiki
Actions Required to Upgrade
You do not need to take any actions for this upgrade other than adjusting your gem file to allow for version 4.0.0 to be included by bundler.
Linked Data Configurations
You may want to update the linked data configurations you are using to avoid a deprecation notice. These configurations are now being versioned with the config format used prior to this release being version 1.0. This releases version is 2.0.
There are several changes from 1.0 to 2.0...
- Configs start by identifying the version number (e.g.
QA_CONFIG_VERSION=2.0). If missing, it is assumed to be 1.0 for backward compatibility. - 2.0 fixes a misuse of IriTemplates in 1.0 where all variables in the template were specified using
{?var}which was expanded tovalue. The specification indicates that variables can be specified as{?var}which expands tovar=valueOR as{var}which expands tovalue. If a config is marked as 1.0 (or not marked with a version) then the incorrect expansion is used for backward compatibility. Going forward the correct expansion is used in 2.0 and later versions. - Configs now support expanded context configuration which allows a site to identify additional data to include in search results that can be used in a UI to facilitate an accurate selection process.
Additional linked data authority configurations that are compatible with the QA linked data module are also defined in LD4P/linked_data_authorities. To use, copy the config file to /config/authorities/linked_data in your app. Additional instructions in the linked_data_authority repository.
v3.0.0
Change Log
- remove agrovoc linked data configuration
Actions Required to Upgrade
You do not need to take any actions for this upgrade. If you are using the Agrovoc authority, see the notes below specific to Agrovoc.
Reason for removal
The API URL for accessing Agrovoc has changed twice since the configuration was originally put in place. This is not sufficiently stable to hold the configuration in QA itself.
Support for Agrovoc has moved to LD4P/linked_data_authorities/qa_agrovoc.
Linked Data Configurations
Additional linked data authority configurations that are compatible with the QA linked data module are also defined in LD4P/linked_data_authorities. To use, copy the config file to /config/authorities/linked_data in your app. Additional instructions in the linked_data_authority repository.
Note for users of Agrovoc authority
At this writing, access to Agrovoc is temporarily unavailable. When the authority owners complete their transition, the Agrovoc authority configuration will be updated.
v2.2.0
Actions Required to Upgrade
You do not need to take any actions to start using this release of questioning authority. It is backward compatible. There are steps to take if you want to use the new reload action. See the instructions below.
Optional New Functionality
Extended linked data API
list
List the installed linked data authorities.
Usage
http://localhost:3000/qa/list/linked_data/authorities
returns json
[
"AGROVOC",
"LOC",
"OCLC_FAST"
]
NOTE: The above list are authorities supplied with QA. Additional configurations that work with the linked data module of QA can be copied from LD4P Linked Data Authorities. The README of that project provides directions of how to install the configs in your app.
reload
To make use of the new linked data authorities reload action, you will need to configure an auth_token. This limits who can take this action.
Enabling in an existing app
- copy
/lib/qa/install/templates/config/initializers/qa.rbto/config/initializers/qa.rb(optional, copy only if you have not already copied this file to your app) - edit this file and uncomment the line setting
config.authorized_reload_tokenand changeYOUR_AUTH_TOKEN_DEFINED_HEREto the value you want to use for the auth token
Enabling in a new app
- run
rails generate qa:install - edit this file and uncomment the line setting
config.authorized_reload_tokenand changeYOUR_AUTH_TOKEN_DEFINED_HEREto the value you want to use for the auth token
Usage
http://localhost:3000/qa/reload/linked_data/authorities?auth_token=YOUR_AUTH_TOKEN
returns the updated list of authorities as json if successful
[
"AGROVOC",
"LOC",
"OCLC_FAST"
]
fetch
This is the same as the existing show action except the URI is passed as a parameter instead of as part of the path.
Usage
- show: http://localhost:3000/qa/show/linked_data/locgenres_ld4l_cache/http%3A%2F%2Fid%2Eloc%2Egov%2Fauthorities%2FgenreForms%2Fgf2011026141
- fetch: http://localhost:3000/qa/fetch/linked_data/locgenres_ld4l_cache?uri=http://id.loc.gov/authorities/genreForms/gf2011026141
NOTES:
- The reason for supporting both actions is that some browsers will convert the encoded %2E back into a period which fails when attempting to request a term through a browser.
- The examples use the locgenres_ld4l_cache authority which is not part of the QA engine. None of the included authorities are configured to request a term by URI. The locgenres_ld4l_cache_authority can be copied into
/config/authorities/linked_datato use the example show and fetch requests.
Return json-ld for a single term
For linked data, you can select to have the term data returned as normalized json (default for backward compatibility) or as json-ld. To get data as json-ld, append ?format=jsonld to a show or fetch API call.
Usage
- show: http://localhost:3000/qa/show/linked_data/locgenres_ld4l_cache/http%3A%2F%2Fid%2Eloc%2Egov%2Fauthorities%2FgenreForms%2Fgf2011026141?format=jsonld
- fetch: http://localhost:3000/qa/fetch/linked_data/locgenres_ld4l_cache?format=jsonld&uri=http://id.loc.gov/authorities/genreForms/gf2011026141
See NOTES for fetch above to see how to test the example show and fetch requests.
Change Log
v2.1.2
Actions Required to upgrade
You do not need to take any actions to start using this release of questioning authority.
Optional New Functionality
QA Linked Data API Documentation
QA can now install API documentation for the linked data module in QA. It uses Swagger-UI for the interactive documentation page that is driven by apidoc.json, a configuration file defining the API using the OpenAPI Specification.
Installation
To install, run the following in your app...
rails g qa:apidoc
This will run the apidoc generator which copies the API documentation into public/qa/apidoc directory in your app.
To view the API documentation, run your app and navigate to...
https://YOUR_HOST_LOCATION/qa/apidoc/
NOTE: The ending / is required for the page to display.
Customizations
You can modify the styles public/qa/swagger-ui.css. Note that this is a compressed CSS file.
You may want to add services to public/qa/apidoc.json for your actual services.
The current definition lets you change the site_host and apiBase to match your installation:
"servers": [
{
"url": "http://{site_host}/{apiBase}",
"description": "QA v2.1 API Server",
"variables": {
"site_host": {
"default": "localhost:3000",
"description": ""
},
"apiBase": {
"default": "qa"
}
}
}
],
In this, you may want to change the default values. apiBase is the location of the QA engine mount in routes. You may also want to add your known server locations which will show up in the drop menu.
"servers": [
{
"url": "http://{site_host}/{apiBase}",
"description": "QA v2.1 API Server",
"variables": {
"site_host": {
"default": "my.production.server",
"description": ""
},
"apiBase": {
"default": "authorities"
}
}
}
{
"url": "http://my.staging.server/authorities",
"description": "QA v2.1 API Server",
}
}
],
Change Log
- add qa:apidoc generator to optionally add QA Linked Data API documentation to app using swagger
Version 2.1.1
See Release Notes for Version 2.1.0 for full description of other changes included in this release.
Bugfix release to address a bug that broke Hyrax.
Change Log
- bugfix that allows application's ApplicationController to interact appropriately with engine's controllers