Skip to content

Instantly share code, notes, and snippets.

@workergnome

workergnome/vocabulary_reconciliation.json Secret

Created October 25, 2019 15:13
Show Gist options
  • Save workergnome/afe5b74cff8f1b4fb6490667cf6a4886 to your computer and use it in GitHub Desktop.
Save workergnome/afe5b74cff8f1b4fb6490667cf6a4886 to your computer and use it in GitHub Desktop.
Download ZIP
Getty Vocabs Reconciliation Open API Spec
Raw
vocabulary_reconciliation.json
{
"openapi": "3.0.0",
"info": {
"title": "Getty Vocabularies Reconciliation Service for OpenRefine",
"description": "Reconciliation service implementing the OpenRefine reconciliation API",
"version": "1.1.0"
},
"servers": [
{
"url": "https://staging-services.aws.getty.edu",
"description": "Staging instance"
},
{
"url": "https://services.getty.edu",
"description": "Main production instance"
}
],
"paths": {
"/vocab/reconcile": {
"get": {
"summary": "Endpoint for reconciliation service",
"description": "Functions as service query interface or service metadata generator",
"externalDocs": {
"description": "OpenRefine API documentation",
"url": "https://github.com/OpenRefine/OpenRefine/wiki/Reconciliation-Service-API"
},
"parameters": [
{
"in": "query",
"name": "callback",
"description": "Callback parameter",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "queries",
"description": "A call to the reconciliation service API",
"required": false,
"schema": {
"type": "string",
"additionalProperties": {
"$ref": "#/components/schemas/queries"
}
},
"example": "{
\"q0\": {
\"query\": \"rhyta\",
\"type\": \"/aat\"
},
\"q1\": {
\"query\": \"vermeer\",
\"type\": \"/ulan\"
},
\"q2\": {
\"query\": \"berlin\",
\"type\": \"/tgn\",
\"limit\": 10,
\"properties\": [
{
\"p\": \"place type\",
\"pid\": \"placeType\",
\"v\": \"inhabited places\"
},
{
\"p\": \"broader place\",
\"pid\": \"broaderExt\",
\"v\": \"Germany\"
}
]
},
\"q3\": {
\"query\": \"white\",
\"limit\": 25
}
}"
}
],
"responses": {
"200": {
"description": "JSON literal object respose to reconciliation query parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/recon"
}
}
}
},
"default": {
"description": "A JSON object with service descriptive information, used by the OpenRefine tool to set parameters needed for reconciliation functionality",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Callback"
}
}
}
}
}
},
"post": {
"summary": "Endpoint for OpenRefine tool",
"description": "Main interface for OpenRefine query functionality",
"externalDocs": {
"description": "OpenRefine API documentation",
"url": "https://github.com/OpenRefine/OpenRefine/wiki/Reconciliation-Service-API"
},
"parameters": [
{
"in": "query",
"name": "queries",
"description": "A call to the reconciliation service API",
"required": false,
"schema": {
"type": "string",
"additionalProperties": {
"$ref": "#/components/schemas/queries"
}
},
"example": "{
\"q0\": {
\"query\": \"rhyta\",
\"type\": \"/aat\"
},
\"q1\": {
\"query\": \"vermeer\",
\"type\": \"/ulan\"
},
\"q2\": {
\"query\": \"berlin\",
\"type\": \"/tgn\",
\"limit\": 10,
\"properties\": [
{
\"p\": \"place type\",
\"pid\": \"placeType\",
\"v\": \"inhabited places\"
},
{
\"p\": \"broader place\",
\"pid\": \"broaderExt\",
\"v\": \"Germany\"
}
]
},
\"q3\": {
\"query\": \"white\",
\"limit\": 25
}
}"
}
],
"responses": {
"200": {
"description": "JSON literal object respose to reconciliation query parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/recon"
}
}
}
},
"default": {
"description": "A JSON object with service descriptive information, used by the OpenRefine tool to set parameters needed for reconciliation functionality",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Callback"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"queries": {
"description": "Query request for reconcilication endpoint",
"type": "object",
"additionalProperties": {
"type": "object",
"description": "JSON object containing query values, types and limit. Key value can be any arbitrary string.",
"properties": {
"query": {
"type": "string",
"description": "A string to search for",
"example": "Berlin"
},
"limit": {
"type": "integer",
"description": "An integer to specify how many results to return",
"example": 10
},
"type": {
"type": "string",
"description": "A single string, or an array of strings, specifying the types of result",
"enum": [ "/ulan", "/aat", "/tgn", "/all" ],
"example": "/tgn"
},
"properties": {
"type": "array",
"description": "Array of json object literals with info on each property to use with search",
"items": {
"type": "object",
"properties": {
"p": {
"type": "string",
"description": "property name",
"example": "broader place"
},
"pid": {
"type": "string",
"description": "property id",
"example": "broaderExt"
},
"v": {
"type": "string",
"description": "string literal of property value",
"example": "Germany"
}
}
}
}
}
}
},
"recon": {
"description": "JSON object containing results of query for a given identifier",
"type": "object",
"properties": {
"randomQueryKey": {
"type": "object",
"description": "JSON object containing search results",
"example": "q0",
"properties": {
"result": {
"type": "array",
"description": "Array of JSON objects with query results",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID and type (AAT, TGN, ULAN) of query result",
"example": "aat/300198841"
},
"name": {
"type": "string",
"description": "Display label for record",
"example": "rhyta"
},
"score": {
"type": "number",
"description": "Score generated by Elasticsearch search algorithm",
"example": 20.340694
},
"match": {
"type": "boolean",
"description": "Boolean value indicating auto-match (not implemented)",
"example": false
},
"type": {
"type": "array",
"description": "Available types the service can query",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Type identifier",
"enum": [ "/ulan", "/aat", "/tgn", "/all" ],
"example": "/aat"
},
"name": {
"type": "string",
"description": "Type descriptive text",
"example": "AAT search"
}
}
}
}
}
}
}
}
}
}
},
"Callback": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the service, which will be used to display the service in the reconciliation menu",
"example": "Getty Vocabularies Reconciliation Service"
},
"identifierSpace": {
"type": "string",
"format": "uri",
"description": "An URI for the type of identifiers returned by the service",
"example": "http://vocab.getty.edu/doc/#GVP_URLs_and_Prefixes"
},
"schemaSpace": {
"type": "string",
"format": "uri",
"description": "An URI for the type of types understood by the service",
"example": "http://vocab.getty.edu/doc/#The_Getty_Vocabularies_and_LOD"
},
"view": {
"type": "object",
"description": "An object with a template URL to view a given item from its identifier",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "Template URL",
"example": "http://vocab.getty.edu/page/{{id}}"
}
}
},
"defaultTypes": {
"type": "array",
"description": "List of different types that can be queried by the service",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Search type identifier",
"enum": [ "/ulan", "/aat", "/tgn", "/all" ],
"example": "/aat"
},
"name": {
"type": "string",
"description": "Search type description",
"example": "AAT search"
}
}
}
},
"preview": {
"type": "object",
"description": "Parameters needed for recon service preview API",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "Templated path for recon preview API",
"example": "http://services.getty.edu/vocab/reconcile/preview?id={{id}}"
},
"height": {
"type": "integer",
"description": "Height of the iFrame that will render the preview HTML",
"example": 200
},
"width": {
"type": "integer",
"description": "Width of the iFrame that will render the preview HTML",
"example": 350
}
}
},
"suggest": {
"type": "object",
"description": "Parameters needed for recon service property suggest API",
"properties": {
"property": {
"type": "object",
"description": "Parameters for property suggest function",
"properties": {
"service_path": {
"type": "string",
"description": "Route for property suggest service",
"example": "/suggest/property"
},
"service_url": {
"type": "string",
"format": "uri",
"description": "Base URL for property suggest service",
"example": "http://services.getty.edu/vocab/reconcile"
}
}
}
}
}
}
}
},
"examples": {
"queries": {
"value": {
"q0": {
"query": "rhyta",
"type": "/aat"
},
"q1": {
"query": "vermeer",
"type": "/ulan"
},
"q2": {
"query": "berlin",
"type": "/tgn",
"limit": 10,
"properties": [
{
"p": "place type",
"pid": "placeType",
"v": "inhabited places"
},
{
"p": "broader place",
"pid": "broaderExt",
"v": "Germany"
}
]
},
"q3": {
"query": "white",
"limit": 25
}
}
}
}
}
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment