# ContentRef

Inline text or file-backed content reference

Canonical URL: https://docs.paradoc.dev/schemas/artifacts/shared/content-ref/

A ContentRef attaches reference content to any artifact. It is a discriminated union keyed on `kind`:

```typescript
type ContentRef = InlineContentRef | FileContentRef
```

ContentRef is used by two optional fields on [ArtifactBase](/schemas/artifacts) (available on all artifact kinds):

| Field               | Purpose                                                                              |
| ------------------- | ------------------------------------------------------------------------------------ |
| `instructions`      | Domain or compliance reference content (e.g., IRS instructions, regulatory guidance) |
| `agentInstructions` | LLM/agent prompts for field ordering, grouping, tone, and presentation guidance      |

## ContentRef Types

### InlineContentRef

Inline content with embedded text. Use when the content is short enough to live directly in the artifact definition.

| Name | Type | Description |
| --- | --- | --- |
| `kind` | `'inline'` | Discriminator for inline content |
| `text` | `string` | The text content (max 1,000,000 characters) |

### FileContentRef

File-backed content reference. Use when the content is large or maintained separately (e.g., a Markdown document alongside the artifact file).

| Name | Type | Description |
| --- | --- | --- |
| `kind` | `'file'` | Discriminator for file content |
| `path` | `string` | Relative path to the content file from the artifact directory |
| `mimeType` | `string` | MIME type of the file content (e.g., text/markdown, text/plain) |
| `title?` | `string` | Human-readable title |
| `description?` | `string` | Description of the content |
| `checksum?` | `string` | SHA-256 checksum for integrity verification (format: sha256:<64 hex chars>) |

## Checksums

The `checksum` field is optional in the schema but recommended for file-backed content references. When present, the CLI verifies integrity during [`validate`](/cli/commands/validate) and [`add`](/cli/commands/add).

* Format: `sha256:` followed by 64 lowercase hex characters
* Use [`paradoc fix`](/cli/commands/fix) to compute or update checksums automatically
* The CLI refuses to download file-backed content references from a registry without a checksum

## Examples



**YAML**

```yaml
# File-backed instructions (large document)
instructions:
  kind: file
  path: ./instructions.md
  mimeType: text/markdown
  title: Form Instructions
  checksum: sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

# Agent instructions (inline)
agentInstructions:
  kind: inline
  text: |
    Present fields in this order: parties first, then property
    details, then financial terms. Use formal tone.
```

**JSON**

```json
{
  "instructions": {
    "kind": "file",
    "path": "./instructions.md",
    "mimeType": "text/markdown",
    "title": "Form Instructions",
    "checksum": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  },
  "agentInstructions": {
    "kind": "inline",
    "text": "Present fields in this order: parties first, then property details, then financial terms. Use formal tone."
  }
}
```

## CLI Support

| Command                              | Behavior                                                                        |
| ------------------------------------ | ------------------------------------------------------------------------------- |
| [`validate`](/cli/commands/validate) | Checks file existence and verifies checksums for file-backed content references |
| [`fix`](/cli/commands/fix)           | Computes or updates checksums for file-backed content references                |
| [`add`](/cli/commands/add)           | Automatically downloads file-backed content reference files from the registry   |
| [`show`](/cli/commands/show)         | Displays content reference info; `--deps` lists referenced files                |
| [`attach`](/cli/commands/attach)     | Attaches a file as instructions or agent instructions (`--as instructions`)     |
| [`detach`](/cli/commands/detach)     | Removes a content reference from an artifact                                    |

## Related

* [Artifact Base Properties](/schemas/artifacts) - Base fields shared by all artifact kinds
* [Layer](/schemas/artifacts/shared/layer) - Rendering output specification (similar file/inline pattern)