# Relationships

A **relationship** is the kind of [link](/data/links/) between two [works](/data/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`](/data/works/attributes/#parent_works). A relationship's OpenAlex ID looks like `https://openalex.org/relationships/volume`; list all five at [`api.openalex.org/relationships`](https://api.openalex.org/relationships), and list a work's links at [`/links`](/data/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`](/data/works/attributes/#parent_works): the works it is part of, each with its relationship.
- [`lineage`](/data/works/attributes/#lineage): the work itself, then every ancestor, nearest first.
- [`child_works_count`](/data/works/attributes/#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](/data/works/corpus/#pieces-of-other-works-are-left-out-too).

### 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 `IsPartOf` another 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.g001`](https://api.openalex.org/works/doi:10.1371/journal.pmed.1000097.g001) is part of `10.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](https://api.openalex.org/works/W7233530818). 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](/data/institutions/#lineage) and publishers: the thing itself plus all of its ancestors. A relationship on each link is how [awards](/data/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`](#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`](https://api.openalex.org/relationships).

## Attributes

The top-level fields on a **relationship** object. Attributes shared with other entities ([`id`](/data/common-attributes/#id), [`display_name`](/data/common-attributes/#display_name), [`works_count`](/data/common-attributes/#works_count), [`created_date`](/data/common-attributes/#created_date), [`updated_date`](/data/common-attributes/#updated_date)) are documented once on [Common attributes](/data/common-attributes/).

### `id`
*String.* The [OpenAlex ID](/data/#the-openalex-id-scheme) 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](#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`, `DCAT` or `CiTO`.
- `term`: the term as that vocabulary spells it, e.g. `isPartOf`.
- `url`: where that vocabulary defines the term.

```json
"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`](https://www.w3.org/ns/dcat#inSeries). `citation` lists Dublin Core's `references`, schema.org's `citation`, DataCite's `References` and `Cites`, Crossref's `references` and [CiTO](http://purl.org/spar/cito/cites)'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](/data/common-attributes/#works_count).

### `works_api_url`
*String.* A ready-made [Works](/data/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](/data/common-attributes/#created_date).

### `updated_date`
*String.* When the record last changed. See [Common attributes](/data/common-attributes/#updated_date).

## In the API

The Relationships endpoint is at [`api.openalex.org/relationships`](https://api.openalex.org/relationships). Fetch one by ID, [`/relationships/volume`](https://api.openalex.org/relationships/volume), or list all five. To list the links themselves, use [`/links`](/data/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](/api/filtering/) for the syntax and the [endpoints index](/api/endpoints/) for every endpoint.

`child_works_count` counts parts in both [corpora](/data/works/corpus/), 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`](https://api.openalex.org/works?filter=parent_works.id:W6931481510&corpus=all) lists the 8 chapters of an IPBES report on Zenodo; without `corpus=all` it lists none.
