{
  "openapi": "3.0.1",
  "info": {
    "title": "DANTE-API",
    "description": "API of DANTE-vocabulary-server. Have a look at https://api.dante.gbv.de/",
    "version": "1.3",
    "contact": {
      "email": "dante-support@lists.gbv.de"
    },
    "license": {
      "name": "Usage is free. Data License is given in each record / vocabulary.",
      "url": ""
    }
  },
  "servers": [
    {
      "url": "https://api.dante.gbv.de"
    },
    {
      "url": "https://dev-api.dante.gbv.de"
    }
  ],
  "paths": {
    "/suggest": {
      "get": {
        "description": "Suggest- and autocompletion-service",
        "summary": "",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "Use the wildcards * and ? to find text in complex forms."
            },
            "example": "Apost"
          },
          {
            "name": "voc",
            "in": "query",
            "style": "pipeDelimited",
            "explode": false,
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/vocParamAsArray"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/typeParam"
            },
            "example": "person"
          },
          {
            "name": "ancestors",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "A DANTE URI. Filter for concepts that are descendants of the specified concept."
            },
            "example": "https://uri.gbv.de/terminology/bk/55"
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/languageParam"
            },
            "example": "fr"
          },
          {
            "name": "use",
            "in": "query",
            "style": "form",
            "explode": false,
            "required": false,
            "schema": {
              "type": "array",
              "uniqueItems": true,
              "items": {
                "type": "string",
                "enum": [
                  "label",
                  "notation"
                ]
              }
            },
            "example": "label"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "alphabet",
                "score"
              ]
            },
            "example": "alphabet"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/limitParam"
            },
            "example": 5
          },
          {
            "name": "cache",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/cacheParam"
            },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/suggest"
          }
        }
      }
    },
    "/search": {
      "get": {
        "description": "Performs a full-text search",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "example": "*"
          },
          {
            "name": "voc",
            "in": "query",
            "style": "pipeDelimited",
            "explode": false,
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/vocParamAsArray"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/typeParam"
            },
            "example": "person"
          },
          {
            "name": "ancestors",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "A DANTE URI. Filter for concepts that are descendants of the specified concept."
            },
            "example": "https://uri.gbv.de/terminology/bk/55"
          },
          {
            "name": "properties",
            "in": "query",
            "style": "form",
            "explode": false,
            "schema": {
              "$ref": "#/components/schemas/propertiesParam"
            }
          },
          {
            "name": "extend",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "dante"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/limitParam"
            },
            "example": 5
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            },
            "example": 0
          },
          {
            "name": "cache",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/cacheParam"
            },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/default"
          }
        }
      }
    },
    "/data": {
      "get": {
        "description": "Information about a concept.",
        "parameters": [
          {
            "name": "uri",
            "in": "query",
            "style": "pipeDelimited",
            "explode": false,
            "schema": {
              "$ref": "#/components/schemas/uriParamAsArray"
            }
          },
          {
            "name": "notation",
            "in": "query",
            "style": "pipeDelimited",
            "explode": false,
            "schema": {
              "$ref": "#/components/schemas/notationParamAsArray"
            }
          },
          {
            "name": "id",
            "in": "query",
            "style": "pipeDelimited",
            "explode": false,
            "schema": {
              "$ref": "#/components/schemas/idParamAsArray"
            }
          },
          {
            "name": "voc",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/vocParamAsString"
            },
            "example": "test"
          },
          {
            "name": "languages",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/languageParam"
            },
            "example": "de,en,fr"
          },
          {
            "name": "properties",
            "in": "query",
            "style": "form",
            "explode": false,
            "schema": {
              "$ref": "#/components/schemas/propertiesParam"
            }
          },
          {
            "name": "extend",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "dante"
              ]
            }
          },
          {
            "name": "cache",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/cacheParam"
            },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/default"
          }
        }
      }
    },
    "/broader": {
      "get": {
        "description": "Returns a list of all direct parent concepts",
        "parameters": [
          {
            "name": "uri",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/uriParamAsString"
            },
            "example": "http://uri.gbv.de/terminology/bk/55"
          },
          {
            "name": "voc",
            "in": "query",
            "style": "pipeDelimited",
            "explode": false,
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/vocParamAsArray"
            },
            "example": "bk"
          },
          {
            "name": "languages",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/languageParam"
            },
            "example": "de,en,fr"
          },
          {
            "name": "properties",
            "in": "query",
            "style": "form",
            "explode": false,
            "schema": {
              "$ref": "#/components/schemas/propertiesParam"
            }
          },
          {
            "name": "extend",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "dante"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/limitParam"
            },
            "example": 5
          },
          {
            "name": "cache",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/cacheParam"
            },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/default"
          }
        }
      }
    },
    "/narrower": {
      "get": {
        "description": "Returns a list of all direct narrower concepts",
        "parameters": [
          {
            "name": "uri",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/uriParamAsString"
            },
            "example": "http://uri.gbv.de/terminology/bk/55"
          },
          {
            "name": "voc",
            "in": "query",
            "style": "pipeDelimited",
            "explode": false,
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/vocParamAsArray"
            },
            "example": "bk"
          },
          {
            "name": "languages",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/languageParam"
            },
            "example": "de,en,fr"
          },
          {
            "name": "properties",
            "in": "query",
            "style": "form",
            "explode": false,
            "schema": {
              "$ref": "#/components/schemas/propertiesParam"
            }
          },
          {
            "name": "extend",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "dante"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/limitParam"
            },
            "example": 5
          },
          {
            "name": "cache",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/cacheParam"
            },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/default"
          }
        }
      }
    },
    "/descendants": {
      "get": {
        "description": "Returns a list of all subordinate concepts",
        "parameters": [
          {
            "name": "uri",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/uriParamAsString"
            },
            "example": "http://uri.gbv.de/terminology/bk/55"
          },
          {
            "name": "voc",
            "in": "query",
            "style": "pipeDelimited",
            "explode": false,
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/vocParamAsArray"
            },
            "example": "bk"
          },
          {
            "name": "languages",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/languageParam"
            },
            "example": "de,en,fr"
          },
          {
            "name": "properties",
            "in": "query",
            "style": "form",
            "explode": false,
            "schema": {
              "$ref": "#/components/schemas/propertiesParam"
            }
          },
          {
            "name": "extend",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "dante"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/limitParam"
            },
            "example": 2
          },
          {
            "name": "cache",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/cacheParam"
            },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/default"
          }
        }
      }
    },
    "/ancestors": {
      "get": {
        "description": "Hierarchy up to a generic term.",
        "parameters": [
          {
            "name": "uri",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/uriParamAsString"
            },
            "example": "http://uri.gbv.de/terminology/bk/55"
          },
          {
            "name": "voc",
            "in": "query",
            "style": "pipeDelimited",
            "explode": false,
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/vocParamAsArray"
            },
            "example": "bk"
          },
          {
            "name": "languages",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/languageParam"
            },
            "example": "de,en,fr"
          },
          {
            "name": "properties",
            "in": "query",
            "style": "form",
            "explode": false,
            "schema": {
              "$ref": "#/components/schemas/propertiesParam"
            }
          },
          {
            "name": "extend",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "dante"
              ]
            }
          },
          {
            "name": "cache",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/cacheParam"
            },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/default"
          }
        }
      }
    },
    "/voc": {
      "get": {
        "description": "Returns a list of all vocabularies or information about a single vocabulary.",
        "parameters": [
          {
            "name": "notation",
            "in": "query",
            "style": "pipeDelimited",
            "explode": false,
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/notationParamAsArray"
            }
          },
          {
            "name": "uri",
            "in": "query",
            "style": "pipeDelimited",
            "explode": false,
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/uriParamAsArray"
            }
          },
          {
            "name": "id",
            "in": "query",
            "style": "pipeDelimited",
            "explode": false,
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/idParamAsArray"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/limitParam"
            },
            "example": "3"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/default"
          }
        }
      }
    },
    "/voc/{vocid}": {
      "get": {
        "description": "Returns information about a vocabulary.",
        "parameters": [
          {
            "name": "vocid",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/notationParamAsString"
            },
            "example": "gender"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/default"
          }
        }
      }
    },
    "/voc/{vocid}/top": {
      "get": {
        "description": "Returns a list of all toplevel records.",
        "parameters": [
          {
            "name": "vocid",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/notationParamAsString"
            },
            "example": "gender"
          },
          {
            "name": "extend",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "dante"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/default"
          }
        }
      }
    },
    "/voc/top": {
      "get": {
        "description": "Returns all concepts marked as topConcepts.",
        "parameters": [
          {
            "name": "uri",
            "in": "query",
            "style": "pipeDelimited",
            "explode": false,
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/uriParamAsArray"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/typeParam"
            },
            "example": "person"
          },
          {
            "name": "extend",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "dante"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/limitParam"
            },
            "example": "3"
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            },
            "example": 0
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/default"
          }
        }
      }
    },
    "/status": {
      "get": {
        "description": "Lists the main endpoints",
        "responses": {
          "200": {
            "$ref": "#/components/responses/default"
          }
        }
      }
    },
    "/ingest": {
      "post": {
        "description": "Perform an ingest in a vocabulary.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "username": {
                    "type": "string",
                    "example": "testuser"
                  },
                  "token": {
                    "type": "string",
                    "example": "3929b8d9-e618-455f-bfdf-4dff475c32b0"
                  },
                  "data": {
                    "type": "object",
                    "description": "JSKOS data object."
                  }
                },
                "required": [
                  "username",
                  "token",
                  "data"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/default"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "default": {
        "description": "JSON-Response in JSKOS-Format",
        "headers": {
          "Access-Control-Allow-Origin": {
            "schema": {
              "type": "string"
            },
            "example": "*"
          },
          "Content-Type": {
            "schema": {
              "type": "string"
            },
            "description": "application/json; charset=utf-8"
          },
          "X-Total-Count": {
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "description": "Total number of hits"
          }
        },
        "content": {
          "application/json; charset=UTF-8": {
            "schema": {
              "type": "string"
            }
          }
        }
      },
      "suggest": {
        "description": "JSON-Response for suggest service",
        "headers": {
          "Access-Control-Allow-Origin": {
            "schema": {
              "type": "string"
            },
            "example": "*"
          },
          "X-Total-Count": {
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          "Content-language": {
            "schema": {
              "type": "string"
            }
          },
          "Content-Type": {
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json; charset=UTF-8": {
            "schema": {
              "type": "string"
            }
          }
        }
      }
    },
    "schemas": {
      "limitParam": {
        "type": "number",
        "minimum": 0,
        "description": "Maximum number of hits to be returned"
      },
      "languageParam": {
        "type": "string",
        "minLength": 2,
        "description": "Alpha-2 code from ISO 639-1. Default is HTTP-Header 'Accept-Language'. Can be passed as a '|'-separated list to get hits from multiple languages."
      },
      "cacheParam": {
        "type": "number",
        "description": "Cache on or off?",
        "enum": [
          0,
          1
        ]
      },
      "vocParamAsArray": {
        "type": "array",
        "uniqueItems": true,
        "description": "An URI or an notation of a DANTE-vocabulary. Can be passed as a '|'-separated list to get hits from multiple vocabularies.",
        "items": {
          "type": "string"
        },
        "example": "test"
      },
      "vocParamAsString": {
        "type": "string",
        "description": "An single URI or an notation of a DANTE-vocabulary.",
        "example": "test"
      },
      "typeParam": {
        "type": "string",
        "description": "An URI or an notation from http://uri.gbv.de/terminology/record_type/. Filter on one or more record types for queries. Can be passed as a '|' or ',' -separated list to get hits from multiple languages.",
        "enum": [
          "work",
          "guideterm",
          "concept",
          "groupconcept",
          "corporate",
          "place",
          "person "
        ]
      },
      "propertiesParam": {
        "type": "string",
        "description": "Selection of desired JSKOS fields. If the parameter is empty, a fixed list of standard fields is assumed, which can vary depending on the request method. With simple selection of fields, only these fields (if any) and some minimal fields such as uri and prefLabel are returned. A single minus stands for only the minimum fields. A single star stands for all fields (standard fields and possibly additional fields). An introduced plus means that additional the standard fields are desired. An introduced minus means that the listed fields are not needed. Available fields: @context,uri,type,prefLabel,topConceptOf,inScheme,altLabel,identifier,notation,publisher,license,scopeNote,definition,startDate,endDate,example,historyNote,note,changeNote,hiddenLabel,narrower,broader,ancestors,mapping,relation,location,depiction,modified"
      },
      "notationParamAsArray": {
        "type": "array",
        "uniqueItems": true,
        "description": "Abbreviation of a vocabulary or signature / number / cipher of a concept",
        "items": {
          "type": "string"
        },
        "example": "11H"
      },
      "notationParamAsString": {
        "type": "string",
        "description": "Abbreviation of a vocabulary or signature / number / cipher of a concept",
        "example": "gender"
      },
      "uriParamAsArray": {
        "type": "array",
        "uniqueItems": true,
        "description": "Unique URI (a record may have multiple URIs but never the other way round)",
        "items": {
          "type": "string"
        },
        "example": "http://uri.gbv.de/terminology/bk/55"
      },
      "uriParamAsString": {
        "type": "string",
        "description": "Unique URI (a record may have multiple URIs but never the other way round)",
        "example": "http://uri.gbv.de/terminology/bk/55"
      },
      "idParamAsArray": {
        "type": "array",
        "uniqueItems": true,
        "description": "Internal identifier",
        "items": {
          "type": "string"
        },
        "example": "http://uri.gbv.de/terminology/bk/55"
      }
    }
  }
}