# `markspec/reference/v1.json`

Reference entry payload (standards, norms, external documents).

**Schema URL:** `https://driftsys.github.io/schemas/markspec/reference/v1.json`

Represents a reference entry for external standards, documents, or norms. Same
base shape as an entry but with different required fields and additional
metadata (document number, external URL, lifecycle status). Produced at
`api/entries/refs/{display-id}.json`.

## Quick guide

- Treat references as first-class nodes with distinct ID rules.
- Use `displayId` pattern for matching external standard IDs.
- Check lifecycle fields (`status`, `supersededBy`) before presenting as active.

## Properties

| Path                 | Type               | Required | Description                                     |
| -------------------- | ------------------ | -------- | ----------------------------------------------- |
| `displayId`          | string             | yes      | Human-readable display ID (e.g., `ISO-26262-6`) |
| `title`              | string             | yes      | Reference title                                 |
| `source`             | string             | yes      | `markdown` or `doc-comment`                     |
| `location`           | object             | yes      | Source location where the reference was defined |
| `location.file`      | string             | yes      | Relative file path from the project root        |
| `location.line`      | integer            | yes      | Line number (1-based)                           |
| `location.column`    | integer            |          | Column number (1-based)                         |
| `id`                 | string             |          | ULID identifier                                 |
| `body`               | string             |          | Reference body rendered as Markdown             |
| `document`           | string \| null     |          | Document number or standard identifier          |
| `externalUrl`        | string \| null     |          | URL to the external document                    |
| `status`             | string \| null     |          | `active`, `superseded`, or `withdrawn`          |
| `supersededBy`       | string \| null     |          | Display ID of the superseding reference         |
| `attributes[]`       | object[]           |          | Custom attributes (`key`, `value` pairs)        |
| `labels`             | string[]           |          | Labels attached to this reference               |
| `createdAt`          | string (date-time) |          | Creation timestamp                              |
| `createdBy`          | string             |          | Creation author                                 |
| `updatedAt`          | string (date-time) |          | Latest update timestamp                         |
| `updatedBy`          | string             |          | Latest update author                            |
| `links`              | object             |          | Incoming links                                  |
| `links.referencedBy` | linkTarget[]       |          | Entries that reference this document            |
| `url`                | string             |          | Relative URL to this reference's detail page    |

## Common pitfall

Do not require `entryType` for references.