Relationships
A relationship is the kind of link between two works: a citation, or a part-of link (a chapter in a book, a figure of a paper, one record of a data series). There are five: citation, and four part-of kinds, one on each entry in a work’s parent_works. A relationship’s OpenAlex ID looks like https://openalex.org/relationships/volume; list all five at api.openalex.org/relationships, and list a work’s links at /links.
About
Parent and child works
Some works are pieces of other works. A book chapter is part of its book, a figure with its own DOI is part of its paper, a data file is part of its dataset. In OpenAlex each of these is a work, and the piece names the whole in its parent_works. We call the piece a child work and the whole a parent work.
Three attributes on every work carry this:
parent_works: the works it is part of, each with its relationship.lineage: the work itself, then every ancestor, nearest first.child_works_count: how many works name it as a parent.
Only part-of links make a parent. Versions of one work (a preprint and its article) are merged into one work. A citation is a link too, but not a parent: its relationship is citation. A dataset behind a paper is its own work, not the paper’s child.
A work can have more than one parent, and a parent can have a parent (a chapter in a book in a book series). There are no loops.
Which child works show by default
A traditional scholarly work (an article, a chapter, a proceedings paper) shows in search and lists whether or not it has a parent. A child that is not a traditional work (front matter, an encyclopedia entry, a figure, a data file) is left out of the default view: you reach it through its parent. The rule is has_parent_work:true and is_traditional:false, nothing else. Add include_parts=true to a works query, or filter on a parent, to see them. Details: Expansion corpus › Pieces of other works.
Where the links come from
Most links come from what the records themselves say; a few we build:
- Books. A chapter, section or reference entry gets its book when the two Crossref records agree on an ISBN, or the chapter’s DOI extends the book’s.
- DataCite. A record gets a parent when it declares
IsPartOfanother DOI and that DOI is also a work. - Figures, tables and files. A record Crossref types as a component gets its paper when its DOI extends the paper’s:
10.1371/journal.pmed.1000097.g001is part of10.1371/journal.pmed.1000097. Most of these records carry no title, so we write one from the kind, the number and the paper (“Figure 1 of …”), and they take their paper’s open access status. Any authors they list keep their names but are not linked to author profiles. - Supplements named after their paper. A record titled “Additional file 1 of” a paper’s title gets that paper, when exactly one work has that title.
- Data series we build. Some sources publish a long run of records without naming the series. For the Large Helical Device, a fusion experiment at the National Institute for Fusion Science, we made one parent work for each instrument’s series of shot records and one work for the whole experiment. These parents have no DOI.
We leave out declared links that can’t be a hierarchy: a record that claims more than 10 parents, two records that each claim to be part of the other, and chains more than 10 levels deep.
Same words as institutions and awards
lineage means what it means on institutions and publishers: the thing itself plus all of its ancestors. A relationship on each link is how awards and institutions describe their own parents and children.
How relationships are named
A relationship’s value is a noun that names the link itself, not one end of it, so it reads the same from either work: citation, component, volume, and later retraction. Its definition reads from the work that carries the link (“The work is …”).
Linked-data vocabularies name the same links with verbs, such as Dublin Core’s isPartOf. Each relationship lists those terms in standard_terms. A standard term can be broader than ours: all four part-of kinds are isPartOf.
Values
| ID | Display name | Definition |
|---|---|---|
citation | Citation | The work cites another work: that work is in its reference list. |
volume | Volume | The work is in a book or proceedings volume: a chapter, entry, front matter or paper of that volume. |
component | Component | The work is a piece of another work that does not stand alone: a figure, table, file or supplement. |
data-series | Data series | The work is one record of a data series: datasets published separately that share an instrument and method. |
part | Part | The work is declared part of another work in some other way: an article in an issue, a dataset in a collection, a component of a project. |
The live list is at api.openalex.org/relationships.
Attributes
The top-level fields on a relationship object. Attributes shared with other entities (id, display_name, works_count, created_date, updated_date) are documented once on Common attributes.
id
String. The OpenAlex ID for this relationship, e.g. https://openalex.org/relationships/volume. The last segment is the value you filter on.
display_name
String. The relationship’s name, e.g. Volume.
description
String. What the relationship means, in a sentence (the definitions in Values).
standard_terms
List of objects. The same link in standard vocabularies, so you can map OpenAlex relationships to linked data. Each object has:
vocabulary: the vocabulary’s name:Dublin Core,schema.org,DataCite,Crossref,DCATorCiTO.term: the term as that vocabulary spells it, e.g.isPartOf.url: where that vocabulary defines the term.
"standard_terms": [
{"vocabulary": "Dublin Core", "term": "isPartOf", "url": "http://purl.org/dc/terms/isPartOf"},
{"vocabulary": "schema.org", "term": "isPartOf", "url": "https://schema.org/isPartOf"},
{"vocabulary": "DataCite", "term": "IsPartOf", "url": "https://datacite-metadata-schema.readthedocs.io/en/4.6/appendices/appendix-1/relationType/#ispartof"},
{"vocabulary": "Crossref", "term": "isPartOf", "url": "https://www.crossref.org/documentation/schema-library/markup-guide-metadata-segments/relationships/"}
]
data-series also lists DCAT’s inSeries. citation lists Dublin Core’s references, schema.org’s citation, DataCite’s References and Cites, Crossref’s references and CiTO’s cites. A standard term can be broader than the relationship: it says the same kind of link, not the same detail.
works_count
Integer. How many works carry this kind of link: works with at least one matched reference for citation, works with a parent of that kind for the others. See Common attributes.
works_api_url
String. A ready-made Works API URL for the works that carry this kind of link (filter=has_references:true for citation, filter=parent_works.relationship:<ID> for the others).
created_date
String. When the relationship was added to OpenAlex (YYYY-MM-DDTHH:MM:SS, an ISO 8601 date and time). See Common attributes.
updated_date
String. When the record last changed. See Common attributes.
In the API
The Relationships endpoint is at api.openalex.org/relationships. Fetch one by ID, /relationships/volume, or list all five. To list the links themselves, use /links.
Relationships are most useful from the works side:
# The parts of one book
https://api.openalex.org/works?filter=parent_works.id:W3109397498
# That book and everything under it, at any depth
https://api.openalex.org/works?filter=lineage:W3109397498
# Works that are part of another work, by kind of link
https://api.openalex.org/works?filter=has_parent_work:true&group_by=parent_works.relationship
# Books with more than 100 parts
https://api.openalex.org/works?filter=type:book,child_works_count:>100
parent_works.id and lineage take a work ID, short (W3109397498) or full. parent_works.relationship takes the short value (volume). See Filtering for the syntax and the endpoints index for every endpoint.
child_works_count counts parts in both corpora, but works lists show the core corpus unless you ask for more. The parts of an expansion work (most Zenodo and repository records are expansion works) are usually expansion works too, so add corpus=all to list them: /works?filter=parent_works.id:W6931481510&corpus=all lists the 8 chapters of an IPBES report on Zenodo; without corpus=all it lists none.
Last updated
View as Markdown