# Citations and CTS URNs

Every text carries a citation, a canonical URL and, where the edition has one, a CTS URN. Any of them can name a text.

Canonical: https://interlinea.aeterna-institute.org/docs/citations

Each text answer says what it is in three ways:

- `citation` is what to quote, such as `Virgil, Aeneid 1.46-86`.
- `url` is the canonical page on Interlinea. `api` and `markdown` are the same resource as JSON and Markdown.
- `urn` is the CTS URN of the passage in its edition, when the edition has one.

From GET /api/v1/text (200 OK):

```json
{
  "citation": "Virgil, Aeneid 1.46-86",
  "ref": "1.46",
  "urn": "urn:cts:latinLit:phi0690.phi003.perseus-lat2:1.46-1.86",
  "url": "https://interlinea.aeterna-institute.org/library/latin/virgil/aeneid/1.46",
  "api": "https://interlinea.aeterna-institute.org/api/v1/library/latin/virgil/aeneid/1.46",
  "markdown": "https://interlinea.aeterna-institute.org/library/latin/virgil/aeneid/1.46.md",
  "work": {
    "title": "Aeneid",
    "url": "https://interlinea.aeterna-institute.org/library/latin/virgil/aeneid",
    "urn": "urn:cts:latinLit:phi0690.phi003"
  }
}
```

## Naming a text

The `ref` of `get_text`, `get_analysis` and `get_context`, and of `/api/v1/text`, `/analysis` and `/context`, takes any of these:

| Form | Example | Notes |
|---|---|---|
| URL or path | `https://interlinea.aeterna-institute.org/library/latin/virgil/aeneid/1.46` | Any host, with or without `.md` or `/api/v1`. |
| Graded passage | `/read/latin/virgil-aeneid` | A passage on the graded path. |
| CTS URN | `urn:cts:latinLit:phi0690.phi003.perseus-lat2:1.46` | A range cites its first line. |
| Citation | `Virgil, Aeneid 1.46` | The words go through catalogue search and the best match wins. |

A citation inside a section returns the section that holds it, so `Aeneid 1.60` returns 1.46-86. A work on its own returns its opening section. An author is answered with a `400` that lists their works.

> A plain citation goes to the best search match, and a shared title can land on the wrong work: Metamorphoses is both Ovid's and Apuleius'. A URL or URN is exact, and every answer names the work it found.

## How a URN maps to a URL

A CTS URN names a passage by text group, work, edition and line. Interlinea's URLs carry the same parts, as names instead of catalogue numbers. Read it like an interlinear text, the URL under the URN:

| Part | In the URN | In the URL |
|---|---|---|
| language | `latinLit` | `latin` |
| author | `phi0690` | `virgil` |
| work | `phi003` | `aeneid` |
| edition | `perseus-lat2` | not in the URL |
| passage | `1.46-1.86` | `1.46` |

Each part takes the colour of the case it would have in a sentence: the language is named (nominative), the text is the author's (genitive), the work is the object (accusative), the edition is the source (ablative) and the passage is the place (locative). The URL leaves the edition out, because every section URL serves the work's default edition, and it cites a section by its first line.

You never have to build the mapping yourself: pass the URN as `ref` and the answer's `url` is the page.

## Which editions have URNs

- Perseus editions are CTS versions, so their URNs name the edition: `urn:cts:latinLit:phi0690.phi003.perseus-lat2:1.46-1.86`.
- Greek Library editions keep the canonical citations but are not CTS versions, so they get the work's URN: `urn:cts:greekLit:tlg0012.tlg001:1.1-1.41`.
- The Latin Library numbers its sections its own way, so its texts have no URN (`urn` is null).
- Graded passages take the URN of their source, when the source link has one.

The edition in a URN is read but not yet honoured: every section URL serves the work's default edition. A work's other editions are listed on it with their credits and URNs.

Pages carry their URN too: work, section and graded-passage pages have `<meta name="DC.identifier">`, and their Markdown has a `CTS URN:` line.

---

Previous: [OpenAPI document](https://interlinea.aeterna-institute.org/docs/api/openapi.md)
Next: [Editions and licences](https://interlinea.aeterna-institute.org/docs/licences.md)