Last edited 6 months ago
by Serena Cericola

GraphQL API

Revision as of 09:02, 8 February 2024 by Andrea Gazzarini (talk | contribs)

Introduction

The Share-VDE Domain Model can be queried using GraphQL.

This page describes the interface in terms of entities, operations, parameters and information related with this interaction mode.

Schema

GraphQL is a schema-based contract interface. That means a domain using GraphQL as interaction protocol must declare a schema where the following things need to be defined:

  • entities
  • attributes
  • operations
  • parameters

A special set of constructs within the protocol/language allow clients to query and introspect the defined schema. Here's an example 

{
  __schema {
    types {
      name
    }
  }
}

which produces the following response (partial):

  "data": {
    "__schema": {
      "types": [
        {
          "name": "Agent"
        },
        {
          "name": "AgentClause"
        },
        {
          "name": "AgentCollection"
        },
        {
          "name": "AgentStructQL"
        },
        ...

More information about the GraphQL introspection capability can be found here; also please keep note the Share-VDE GraphiQL UI provides a navigable section which queries the schema and provides the introspection data in a human-readable way (see the Docs link on the right side of the UI).

Directives

At time of writing there's only one directive in the Share-VDE GraphQL Schema: it is called "availableOnlyFor" and it is used to mark protected resources that require a privileged role for their access.

See the following schema extract:

{
 type Provenance {
    uri: ID!

    code: String

    description: String

    status: [RuntimeClusterStatus] @availableOnlyFor(role: "svde-editor-base")
}

In the example, the status field is accessible only if the requestor has a svde-editor-base (or higher) role associated. Otherwise it will return null.

Top Level Queries

exactMatches

A special search which targets only entities whose headings or identifiers match exactly the whole query or a part of it.

The following scenarios are detected as exact matches:

  • identifiers (regardless their position within the query string)
  • single identifier: (e.g. a query composed only by an identifier like barcodeXYZ, 978-00023-23372-23, 201)
  • single heading: (e.g. a title or a name, like Alice’s adventures in Wonderland)
  • headings match is diacritic, whitespaces, punctuation and case insensitive: Alice’s ADVenTUREs in WONDERlAnD,Alice’s ADVenTUREs in WONDERlAnD, Alice’s/ADVenTUREs.in__WONDERlAnD,Alìcè’s àDVènTURès ìn WòNDERlAnD
  • identifier followed by a heading: barcodeXYZ Alice’s adventures in Wonderland
  • heading followed by an identifier:Alice’s adventures in Wonderland barcodeXYZ
  • a heading between two identifiers: barcodeXYZ Alice’s adventures in Wonderland 201
  • one or more identifiers mixed with text terms: barcodeXYZ adventures 201 Wonderland 978-00023-23372-23, 404

Outside the scenarios above, there are some cases where headings (i.e. titles, names) are not properly detected. This is an example list of those cases (coloured entities are detected, strikethrough headings don't):

  • headings after multiple identifiers: barcodeXYZ 978-00023-23372-23 201 Alice’s adventures in Wonderland
  • headings before multiple identifiers: Alice’s adventures in Wonderland barcodeXYZ 978-00023-23372-23 201
  • headings between multiple terms: barcodeXYZ 978-00023-23372-23 Alice’s adventures in Wonderland 201 404

Request & Response

Input Parameters
Name Type Description Cardinality
q String A query string composed by one or more search terms 0...1
filter String One of the following values
  • AGENT
  • INSTANCE (used for publications)
  • OPUS
  • ITEM


In case the filter should consider multiple entity types, they have to be surrounded by parenthesis.

For example

  • (AGENT INSTANCE)
  • (AGENT OPUS)
 1

Example:

{
	exactMatches(q:"201 Alice’s adventures in Wonderland I0003", filter:"AGENT") {
    resources {
      __typename
      
    }
  }
}

The response is a collection containing the first most relevant entity whose headings or identifiers match exactly the whole input or a part of it. Example (this is the response of the sample request above):

{
  "data": {
    "exactMatches": {
      "resources": [
        {
          "__typename": "Person"
        }
      ]
    }
  }
}

Simple search

Simple search uses a basic query approach. That means the query is supposed to contains only terms (and optionally modifiers).

Request & Response

Input Parameters
Name Type Description Cardinality
q String One or more terms 0...1
sortSpecs String A valid sort clause N.A.
offset Integer A positive integer indicating the start offset of results 0
rows Integer A positive integer indicating the returned page size 10
partialMatch Boolean If set to true skips the full match and moves directly to partial match 0...1
filters Array of Strings Zero or more filters used for refining search results 0...n

The response is a collection of agents and opuses matching the search criteria. A collection is itself an entity whose metadata can differ depending on the search type that has been triggered.

A response provides the following sections:

  • resources: a sublist of the matching agents according with the pagination parameters in the request. Each agent in the resources list is represented using the attribute indicated in the request (if they are not null). Note that an agent can have datatype and/or object properties, with different cardinalities. That means a representation is not only composed by datatype (literal) attributes but could also involve other entities (e.g. opuses belonging to an agent)
  • pagination
  • matchMode: informs the caller about the query logic that has been executed. Possible values are
    • FULL: it indicates that an AND logic between query terms has been applied
    • PARTIAL: it indicates that an OR logic between query terms has been applied
    • SERVER_DEFINED: (advanced search only) when the search logic that has been executed cannot be summarised/simplified using the mnemonic codes above.
    • USER_DEFINED: in case of simple search where at least one query term is prefixed by a mandatory (+) or unwanted (-) modifier.

agents

Search across all agents using one available query language.

Request & Response

Note that in this specific case, since we are querying the generic entity "agents" and we don't know the agents type in advance, the request has to make use of the special "...on <entity type>" GraphQL construct in order to differentiate the attributes we want to get back depending on the concrete agent type (see the examples below).

Input Parameters
Name Type Description Cardinality
svdeql SVDEQL A query expressed in SVDEQL (includes sort and pagination) 0...1
stql AgentStructQL A query expressed in StructQL (includes sort and pagination) 0...1
tql TermsQL A query expressed in TermsQL (Typeahead search) 0...1
filters Array of Strings Zero or more filters used for refining search results 0...n
refinementQuery String One or more terms used for filtering on all entity attributes 0...1

Filters apart, the other parameters are three different ways to express a search need (i.e. a query).

Specifically

  • svdeql and stql are used for triggering a fulltext search
  • tql is meant to be used in a typeahead context (e.g. autocompletion, suggesters)

The response is a collection of agents matching the search criteria. A collection is itself an entity whose metadata can differ depending on the search type that has been triggered.

A response provides the following sections:

  • resources: a sublist of the matching agents according with the pagination parameters in the request. Each agent in the resources list is represented using the attribute indicated in the request (if they are not null). Note that an agent can have datatype and/or object properties, with different cardinalities. That means a representation is not only composed by datatype (literal) attributes but could also involve other entities (e.g. opuses belonging to an agent)
  • facets
    • beginningDate: virtual attribute with a different meaning depending on the agent type (e.g. startDate for families, birthDate for people)
    • endingDate: virtual attribute with a different meaning depending on the agent type (e.g. endDate for families, deathDate for people)
    • location: virtual attribute with a different meaning depending on the agent type (e.g. birth or death place for people)
  • pagination
  • matchMode: informs the caller about the query logic that has been executed. Possible values are
    • FULL: it indicates that an AND logic between query terms has been applied
    • PARTIAL: it indicates that an OR logic between query terms has been applied
    • SERVER_DEFINED: (advanced search only) when the search logic that has been executed cannot be summarised/simplified using the mnemonic codes above.
    • USER_DEFINED: in case of simple search where at least one query term is prefixed by a mandatory (+) or unwanted (-) modifier.

A response of a typeahead search (tql) still provide those sections above, however

  • headings contain highlighting snippets (that can be used for example in suggesters UI)
  • it is not recommended in those scenarios to ask facets and metadata other than headings
  • pagination metadata are always set to zero

Note that also typeahead search results provide a poor results in terms of metadata; however they contain snippets for highlighting the matching ngrams (so the caller can better understand why a given result matched). Here's an extract of the typeahead search response:

{
  "data": {
    "agents": {
      "resources": [
        {
          "uri": "https://svde.org/agents/217",
          "preferredHeading": "Bonham <b>Carte</b>r, Helena"
        },
        {
          "uri": "https://svde.org/agents/202",
          "preferredHeading": "<b>Carro</b>ll, Alfred Ludlow"
        },
        {
          "uri": "https://svde.org/agents/203",
          "preferredHeading": "<b>Carro</b>ll, Adam (Adam Paul)"
        },
        {
          "uri": "https://svde.org/agents/201",
          "preferredHeading": "<b>Carro</b>ll, Lewis"
        }
      ]
    }
  }
}

Actually it's possible to ask for more metadata and facets even in typeahead scenarios, but it is generally a not recommended usage because the service in these cases must be as fast as possible (suggestions must be displayed immediately after the user presses keys)

For typeahead scenarios, RESTful API are definitely recommended, because the different paradigm moves on the server side the responsibility to define the response shape, and therefore to optimize the interaction process.

agent

Retrieves the agent associated with a URI.

Request

As in the previous operation (agents) we are querying the generic "agent" entity and therefore we don't know its type in advance. The request has to make use of the special ...on <entity type> GraphQL construct in order to differentiate the attributes we want to get back depending on the concrete agent type (see the examples below).

Input Parameters
Name Type Description Cardinality
uri Share-VDE URI The Share-VDE URI associated with the agent we want to retrieve 1
Response

The response is the agent associated with the input URI, if that exists. The exact agent representation, in terms of attributes, depends on the request shape.

people

Search across all people using one available query language. Input parameters are the same we already described in the Agent section and also the response includes the same sections already described for the agents. Differences are:

  • resources: consist of a sublist of the matching people according with the pagination parameters in the request.
  • facets
    • birthPlace: entities of type Place. For each bucket we can ask the URI, the label and the count
    • birthDate: the birth year (that is not the full date)
    • occupation: entities of type Occupation. For each bucket we can ask the URI, the label and the count
    • deathPlace: entities of type Place. For each bucket we can ask the URI, the label and the count
    • deathDate: the birth year (that is not the full date)
  • pagination
  • matchMode: informs the caller about the query logic that has been executed. Possible values are
    • FULL: it indicates that an AND logic between query terms has been applied
    • PARTIAL: it indicates that an OR logic between query terms has been applied
    • SERVER_DEFINED: (advanced search only) when the search logic that has been executed cannot be summarised/simplified using the mnemonic codes above.
    • USER_DEFINED: in case of simple search where at least one query term is prefixed by a mandatory (+) or unwanted (-) modifier.

person

Retrieves the person associated with a URI.


Request & Response

The request accepts a single parameter which is the Share-VDE URI of the person we are looking for.

Input Parameters
Name Type Description Cardinality
uri Share-VDE URI The Share-VDE URI associated with the person we want to retrieve 1

The response is the person associated with the input URI, if that exists. The exact person representation, in terms of attributes, depends on the request shape (i.e. the person attributes that have been indicated in the request).

meetings

Search across all meetings using one available query language. Input parameters are the same we already described in the Agent section and also the response includes the same sections already described for the agents. Differences are:

  • resources: consist of a sublist of the matching meetings according with the pagination parameters in the request.
  • facets
    • year: the meeting year (that is not the full date)
    • location: entities of type Place. For each bucket we can ask the URI, the label and the count
  • pagination
  • matchMode: informs the caller about the query logic that has been executed. Possible values are
    • FULL: it indicates that an AND logic between query terms has been applied
    • PARTIAL: it indicates that an OR logic between query terms has been applied
    • SERVER_DEFINED: (advanced search only) when the search logic that has been executed cannot be summarised/simplified using the mnemonic codes above.
    • USER_DEFINED: in case of simple search where at least one query term is prefixed by a mandatory (+) or unwanted (-) modifier.

meeting

Retrieves the meeting associated with a URI.


Request & Response

The request accepts a single parameter which is the Share-VDE URI of the meeting we are looking for.

Input Parameters
Name Type Description Cardinality
uri Share-VDE URI The Share-VDE URI associated with the meeting we want to retrieve 1

The response is the meeting associated with the input URI, if that exists. The exact meeting representation, in terms of attributes, depends on the request shape (i.e. the meeting attributes that have been indicated in the request).

organisations

Search across all organisations using one available query language. Input parameters are the same we already described in the Agent section and also the response includes the same sections already described for the agents. Differences are:

  • resources: consist of a sublist of the matching organisations according with the pagination parameters in the request.
  • facets
    • foundingYear: the year (not the full date) an organisation has been founded
    • dissolutionYear: the year (not the full date) an organisation has been dissolved
    • location: entities of type Place. For each bucket we can ask the URI, the label and the count
  • pagination
  • matchMode: informs the caller about the query logic that has been executed. Possible values are
    • FULL: it indicates that an AND logic between query terms has been applied
    • PARTIAL: it indicates that an OR logic between query terms has been applied
    • SERVER_DEFINED: (advanced search only) when the search logic that has been executed cannot be summarised/simplified using the mnemonic codes above.
    • USER_DEFINED: in case of simple search where at least one query term is prefixed by a mandatory (+) or unwanted (-) modifier.

organisation

Retrieves the organisation associated with a URI.


Request & Response

The request accepts a single parameter which is the Share-VDE URI of the organisation we are looking for.

Input Parameters
Name Type Description Cardinality
uri Share-VDE URI The Share-VDE URI associated with the organisation we want to retrieve 1

The response is the organisation associated with the input URI, if that exists. The exact organisation representation, in terms of attributes, depends on the request shape (i.e. the attributes that have been indicated in the request).

families

Search across all families using one available query language. Input parameters are the same we already described in the Agent section and also the response includes the same sections already described for the agents. Differences are:

  • resources: consist of a sublist of the matching families according with the pagination parameters in the request.
  • facets
    • endDate: the year (not the full date) a family appeared
    • startDate: the year (not the full date) a family disappeared
  • pagination
  • matchMode: informs the caller about the query logic that has been executed. Possible values are
    • FULL: it indicates that an AND logic between query terms has been applied
    • PARTIAL: it indicates that an OR logic between query terms has been applied
    • SERVER_DEFINED: (advanced search only) when the search logic that has been executed cannot be summarised/simplified using the mnemonic codes above.
    • USER_DEFINED: in case of simple search where at least one query term is prefixed by a mandatory (+) or unwanted (-) modifier.

family

Retrieves the family associated with a given URI.


Request & Response

The request accepts a single parameter which is the Share-VDE URI of the family we are looking for.

opuses

Search across all agents using one available query language.


Request & Response

Input Parameters
Name Type Description Cardinality
svdeql SVDEQL A query expressed in SVDEQL (includes sort and pagination) 0...1
stql AgentStructQL A query expressed in StructQL (includes sort and pagination) 0...1
filters Array of Strings Zero or more filters used for refining search results 0...n
refinementQuery String One or more terms used for filtering on all entity attributes 0...1

Filters apart, the other parameters are two different ways to execute a fulltext search (i.e. a query).

The response is a collection of opuses matching the search criteria.

The response provides 3 sections:

  • resources: a sublist of the matching opuses according with the pagination parameters in the request. Each entity in the resources list is represented using the attribute specified in the request (if they are not null).
  • facets
    • contributor: contributors (as URIs) associated with the opuses in results
    • year: years associated with the opuses in results
    • format: the formats (as URIs) of the publication indirectly associated with the opuses in results
    • genre: the genres (as URIs) associated with the opuses in results
  • pagination
  • matchMode: informs the caller about the query logic that has been executed. Possible values are
    • FULL: it indicates that an AND logic between query terms has been applied
    • PARTIAL: it indicates that an OR logic between query terms has been applied
    • SERVER_DEFINED: (advanced search only) when the search logic that has been executed cannot be summarised/simplified using the mnemonic codes above.
    • USER_DEFINED: in case of simple search where at least one query term is prefixed by a mandatory (+) or unwanted (-) modifier.

opus

Retrieve the opus associated with a given URI. Note that the result in this case is the same type of the nth result in the collection of the previous operation. That means everything we can ask to this entity in terms of attribute and operations can be also indicated/requested in the previous operation (for each matching opus).

The request accepts a single parameter which is the Share-VDE URI of the opus we are looking for.

Note the Opus is the top level entity of the bibliographic chain composed by Opus-Works-Instances-Items. That means starting from a given Opus we can explore the corresponding hierarchy down to the item leaves (see the last example below).

Input Parameters
Name Type Description Cardinality
uri Share-VDE URI The Share-VDE URI associated with the opus we want to retrieve 1

Request & Response The response is the opus associated with the input URI, if that exists. The exact resource representation, in terms of attributes, depends on the request shape (i.e. the attributes that have been indicated in the request).

work

Retrieve the work associated with a given URI. The request accepts a single parameter which is the Share-VDE URI of the Work we are looking for.

A Work is the 2nd level entity of the bibliographic Opus-Works-Instances-Items hierarchy. That means starting from a given Work we can explore the whole hierarchy down to the item leaves (see the last example below).

Input Parameters
Name Type Description Cardinality
uri Share-VDE URI The Share-VDE URI associated with the work we want to retrieve 1

Request & Response The response is the work associated with the input URI, if that exists. The exact resource representation, in terms of attributes, depends on the request shape (i.e. the attributes that have been indicated in the request).

instance

Retrieve the instance associated with a given URI. The request accepts a single parameter which is the Share-VDE URI of the target Instance.

An Instance is the 3rd level entity of the bibliographic Opus-Works-Instances-Items hierarchy. That means starting from a given Instance we can explore the whole hierarchy down to the item leaves (see the last example below).

Input Parameters
Name Type Description Cardinality
uri Share-VDE URI The Share-VDE URI associated with the instance we want to retrieve 1

Request & Response The response is the instance associated with the input URI, if that exists. The exact resource representation, in terms of attributes, depends on the request shape (i.e. the attributes that have been indicated in the request).

The Instance entity provides a connection to the bibliographic records that contributed to its definition. Specifically, when at least one of those connections is available, a "seeAlso" attribute will contain the links to the corresponding OPACs. Each link is composed by the URL and the owning provenance (code). Here's an example:

{
  "data": {
    "instance": {
      "preferredHeading": "Aventures d'Alice au pays des merveilles",
      "seeAlso": [
          {
              "url": "https://searchworks.stanford.edu/view/9386906",
              "qualifier": "STANFORD"
          },
          ...
        ]
    }
  }
}

item

Retrieve the item associated with a given URI. The request accepts a single parameter which is the Share-VDE URI of the item we are looking for.

publications

Search across all agents using one available query language.


Request & Response

Input Parameters
Name Type Description Cardinality
svdeql SVDEQL A query expressed in SVDEQL (includes sort and pagination) 0...1
stql PublicationStructQL A query expressed in StructQL (includes sort and pagination) 0...1
filters Array of Strings Zero or more filters used for refining search results 0...n
refinementQuery String One or more terms used for filtering on all entity attributes 0...1

Filters apart, the other parameters are two different ways to execute a fulltext search (i.e. a query).

The response is a collection of publications matching the search criteria.

The response provides 3 sections:

  • resources: a sublist of the matching publications according with the pagination parameters in the request.
  • facets
    • publicationPlace: the (instance) publication place
    • format: the formats (as URIs) of the publication indirectly associated with the opuses in results
    • publicationYear: the (instance) publication year
  • pagination

publication

Retrieve the publication associated with a given URI. A publication is a logical entity which includes:

  • an instance
  • the parent work
  • the items

The operation accepts a single parameter which is the Share-VDE URI of the publication we are looking for.

Input Parameters
Name Type Description Cardinality
uri Share-VDE URI The Share-VDE URI associated with the publication we want to retrieve 1

The response is the publication associated with the input URI, if that exists. The exact resource representation, in terms of attributes, depends on the request shape (i.e. the attributes that have been indicated in the request).

Controlled Vocabulary Entities

The Controlled Vocabulary group includes all those entities that are not part of the core group. The list includes:

  • OpusType
  • AgentType
  • SubjectType
  • Availability
  • Place
  • Language
  • Occupation
  • Genre
  • Form
  • Role
  • Format

Apart attributes that are specific to a given entity type (e.g. a Place could have a "coordinates" attribute) the whole group shares the following structure:

1623235578601.png

Core Entities

The Share-VDE Domain is a mix of technical and functional entities that models the complex world needed for expressing the Share-VDE dataset. In this section we will detail those entities and their capabilities in terms of state and operations.

Before going ahead, it's important to highlight a general assumption:

  • each Share-VDE entity is uniquely identified by a Share-VDE URI (e.g. https://svde.org/agents/201)
  • Opus, Work, Instance and Publication provide a "contributors" endpoint as explained here.

Agent

The Agent is an abstract concept which concretely maps people, organisations, conferences, families, jurisdictions, etc., that play a role (or even multiple roles) such as authors, editors, distributors, illustrator, publisher, etc.

Being an abstract super-type layer an agent doesn't provides any attribute: its state (e.g. attributes) depends on the underlying concrete type.

There are several places where the interface accepts or returns this entity without making any assumption about the concrete agent type; for example, when we ask for the contributors of a given work, each contributor can be a family or a person, or an organisation. For that reason, the interface returns them as "agents"; the requestor can then inspect the response in order to differentiate between their concrete type.

There are no operations exposed at agent level: as in the previous operation (agents) we are querying the generic "agent" entity and therefore we don't know its type in advance. The request has to make use of the special ...on <entity type> GraphQL construct in order to differentiate the attributes we want to get back depending on the concrete agent type (see the examples below).

Person

A person is an individual or identity established by an individual (either alone or in collaboration with one or more other individuals). It is a concrete subclass of Agent and provides a set of attributes, both datatype and object properties which interconnect the entity to opuses and other bibliographic entities in the Share-VDE domain model.

The available operations of the Person entity are semantically identical to what we already described for the abstract Agent entity. However, in this context everything is typed to be a Person entity so there's no need, on the requestor side, to make any assumption about the returned entities type (i.e. there's no need to make use of that ... on <entity type> GraphQL construct).

occupations

Retrieves the list of Occupation (see the Controlled Vocabulary Entities section above) associated to a given person.

identifiers

Retrieves the list of SameAs associated to a given person. A SameAs is a simple entity composed by

  • a URI
  • a source mnemonic code (e.g. viaf, isni)

opuses

Retrieves the list of Opuses a given person contributed to. The list could optionally include the opuses a given person is subject of.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
role String Includes only opuses a given agent played a specific role 0...1 N.A.
about Boolean If set to true, the results includes also opuses a given person is subject of 0...1 false
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

publications

Retrieves the list of Publications a given person contributed to.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
role String Includes only publications a given agent played a specific role 0...1 N.A.
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

Meeting

Gathering of individuals or representatives of various bodies for the purpose of discussing and/or acting on topics of common interest. It is a concrete subclass of Agent and provides a set of attributes, both datatype and object property which interconnect the entity to opuses and other bibliographic entities in the Share-VDE domain model.

The available operations of the Meeting entity are semantically identical to what we already described for the abstract Agent entity. However, in this context everything is typed to be a Meeting so there's no need, on the requestor side, to make any assumption about the returned entities type.

identifiers

Retrieves the list of SameAs associated to a given meeting. A SameAs is a simple entity composed by

  • a URI
  • a source mnemonic code (e.g. viaf, isni)

opuses

Retrieves the list of Opuses a given meeting contributed to. The list could optionally include the opuses a given meeting is subject of.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
role String Includes only opuses a given agent played a specific role 0...1 N.A.
about Boolean If set to true, the results includes also opuses a given meeting is subject of 0...1 false
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

publications

Retrieves the list of Publications a given meeting contributed to.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
role String Includes only publications a given agent played a specific role 0...1 N.A.
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

Organisation

A corporation or group of persons and/or organisations that acts, or may act, as a unit. It is a concrete subclass of Agent and provides a set of attributes, both datatype and object property which interconnect the entity to opuses and other bibliographic entities in the Share-VDE domain model.

The available operations of the Organisation entity are semantically identical to what we already described for the abstract Agent entity. However, in this context everything is typed to be an Organisation so there's no need, on the requestor side, to make any assumption about the returned entities type.

identifiers

Retrieves the list of SameAs associated to a given organisation. A SameAs is a simple entity composed by

  • a URI
  • a source mnemonic code (e.g. viaf, isni)

opuses

Retrieves the list of Opuses a given organisation contributed to. The list could optionally include the opuses a given organisation is subject of.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
role String Includes only opuses a given agent played a specific role 0...1 N.A.
about Boolean If set to true, the results includes also opuses a given organisation is subject of 0...1 false
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

publications

Retrieves the list of Publications a given organisation contributed to.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
role String Includes only publications a given agent played a specific role 0...1 N.A.
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

Family

Two or more persons related by birth, marriage, adoption, civil union, or similar legal status, or who otherwise present themselves as a family. It is a concrete subclass of Agent and provides a set of attributes, both datatype and object property which interconnect the entity to opuses and other bibliographic entities in the Share-VDE domain model.

The available operations of the Family entity are semantically identical to what we already described for the Agent entity. However, in this context everything is typed to be a Family so there's no need, on the requestor side, to make any assumption about the returned entities type.

identifiers

Retrieves the list of SameAs associated to a given family. A SameAs is a simple entity composed by

  • a URI
  • a source mnemonic code (e.g. viaf, isni)

opuses

Retrieves the list of Opuses a given family contributed to. The list could optionally include the opuses a given family is subject of.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
role String Includes only opuses a given agent played a specific role 0...1 N.A.
about Boolean If set to true, the results includes also opuses a given family is subject of 0...1 false
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

publications

Retrieves the list of Publications a given family contributed to.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
role String Includes only publications a given agent played a specific role 0...1 N.A.
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

Opus

The highest level of abstraction, a Work, in the BIBFRAME context, reflects the conceptual essence of the cataloged resource: authors, languages, and what it is about[1].

identifiers

Retrieves the list of SameAs associated to a given family. A SameAs is a simple entity composed by

  • a URI
  • a source mnemonic code (e.g. viaf, isni)

contributors

Retrieves the list of agents that contributed to a given opus. The list could optionally include the agents that are name subject of the opus.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
role String Includes only opuses a given agent played a specific role 0...1 N.A.
includeNameSubject Boolean If set to true, the results includes also name subjects 0...1 false
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

works

Retrieves the list of works belonging to a given opus.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

articles

Retrieves the articles (ki.e. child opuses) of a given journal or multivolume Opus.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

chapters

Retrieves the list of chapters (i.e.child opuses) belonging to a given opus.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

volumes

Retrieves the list of volumes (i.e. the publications of child opuses) belonging to a given opus.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

works

Retrieves the series belonging to a given opus.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

Work

An intermediate level of abstraction which reflects an expression of a given Opus.

contributors

Retrieves the list of agents that contributed to a given work.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
role String Includes only opuses a given agent played a specific role 0...1 N.A.
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

instances

Retrieves the list of instances belonging to a given work.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

subjects

Retrieves the list of subjects associated to a given work.

Instance

A Work may have one or more individual, material embodiments, for example, a particular published form. These are Instances of the Work. An Instance reflects information such as its publisher, place and date of publication, and format[1].

contributors

Retrieves the list of agents that contributed to a given instance.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
role String Includes only opuses a given agent played a specific role 0...1 N.A.
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

items

Retrieves the list of items belonging to a given instance.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

Publication

A publication is a logic entity which groups an instance, its items and the parent work.

work

Returns the work of a given publication.

instance

Returns the instance of a given publication.

contributors

Retrieves the list of agents that contributed to a given publication.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
role String Includes only opuses a given agent played a specific role 0...1 N.A.
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

items

Retrieves the list of items belonging to a given publication.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

like

Retrieves the list of publications that have the same format and same language of a given publication.

Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.

additionalFormats

Retrieves the list of the same publications available in other formats. Note that starting with a publication P1 whose format is X, the additionalFormats "group" could potentially include another publication P2 whose format is still X.

If the caller wants to exclude a priori that format (X, in the example above) the "excludeFormat" parameter should be used.

IMPORTANT: although the "additionalFormats" field consists of a set of publications, please remember that

  • it doesn't support the grouping feature
  • it doesn't support faceting
Request Parameters
Name Type Description Cardinality Default Value
sort String A valid sort clause 0...1 N.A.
offset Integer A positive integer indicating the start offset of results 0...1 0
rows Integer A positive integer indicating the returned page size 0...1 10
filters String An array of filter clauses used for refining search results 0...n N.A.
refinementQuery String One or more terms used for filtering on all entity attributes 0...1 N.A.
excludeFormat String the URI of a format we want to exclude from the search results 0...1 N.A.

Here's an example request:

{
  publication(uri: "https://svde.org/publications/I0160") {
    additionalFormats {
      resources {
        uri
        instance {
          format {
            uri
            label
          }
        }
      }
    }
  }
}

and the corresponding response:

{
  "data": {
    "publication": {
      "additionalFormats": {
        "resources": [
          {
            "uri": "https://svde.org/publications/I0161",
            "instance": {
              "format": {
                "uri": "https://svde.org/formats/pp",
                "label": "Microscope slide"
              }
            }
          },
          {
            "uri": "https://svde.org/publications/I0136",
            "instance": {
              "format": {
                "uri": "https://svde.org/formats/nc",
                "label": "Volume"
              }
            }
          }
        ]
    }
  }
}

------

  1. ↑ 1.0 1.1 https://www.loc.gov/bibframe/docs/bibframe2-model.html
Retrieved from "https://wiki.share-vde.org/w/index.php?title=ShareDoc:GraphQL_API&oldid=2052"