> ## Documentation Index
> Fetch the complete documentation index at: https://docs.docyard.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Artifact Types

> Templates that define document categories and their lock requirements

# Artifact Types

When uploading an artifact to the lake, distributors MUST select an **Artifact Type**. This is a template that defines:

1. What type of document is being uploaded
2. What lock types are required
3. What lock types are optional
4. Default weights for each lock

## Why Artifact Types?

Without artifact types, distributors would manually define locks for every upload. This leads to:

* **Inconsistency**: One upload has `policy_number`, another has `policy_num`
* **Missing fields**: Important locks forgotten
* **Incompatible weights**: Same lock has different weights across uploads

Artifact types enforce consistency and structure.

## Template Structure

Each artifact type template contains:

| Field           | Description                  | Example                                         |
| --------------- | ---------------------------- | ----------------------------------------------- |
| **Name**        | Human-readable document type | "Insurance Declaration Page"                    |
| **Description** | What this document is        | "Standard insurance policy declaration"         |
| **Owner**       | Who created this template    | Distributor ID                                  |
| **Status**      | Lifecycle stage              | draft, pending\_approval, published, deprecated |
| **Locks**       | List of lock definitions     | See below                                       |

### Lock Definitions

Each lock in a template has:

| Field           | Description               | Example                       |
| --------------- | ------------------------- | ----------------------------- |
| **Name**        | Lock type identifier      | `policy_number`               |
| **Data Type**   | What kind of value        | string, number, date, boolean |
| **Description** | What this lock represents | "Insurance policy number"     |
| **Validation**  | Rules for the value       | regex, min/max length         |
| **Weight**      | Default weight score      | 20                            |
| **Required**    | Is this lock mandatory?   | true/false                    |

### Example: Insurance Declaration Template

```json theme={null}
{
  "name": "Insurance Declaration Page",
  "description": "Standard insurance policy declaration document",
  "status": "published",
  "locks": [
    {
      "name": "policy_number",
      "data_type": "string",
      "description": "Insurance policy number",
      "validation": { "pattern": "^POL-[0-9]{8}$" },
      "weight": 20,
      "required": true
    },
    {
      "name": "effective_date",
      "data_type": "date",
      "description": "Policy effective date",
      "weight": 10,
      "required": true
    },
    {
      "name": "mortgagee_name",
      "data_type": "string",
      "description": "Name of mortgagee/lender",
      "weight": 5,
      "required": false
    },
    {
      "name": "address",
      "data_type": "string",
      "description": "Property address",
      "weight": 5,
      "required": false
    }
  ]
}
```

## Private vs Shared Templates

### Private Templates

Created by a single distributor for their own use.

```
✅ Acme Insurance → "Acme Declaration Page"
✅ Acme Insurance → "Acme Endorsement"
✅ Acme Insurance → "Acme Renewal Notice"
```

**Characteristics:**

* Only the creator can use them
* No conflicts with other distributors
* Full flexibility to customize

### Shared Templates

Curated by Docyard admins for industry-wide use.

```
✅ Docyard Admin → "Insurance Declaration (Standard)"
✅ Docyard Admin → "Insurance Endorsement (Standard)"
```

**Characteristics:**

* Any distributor can use them
* Ensures consistency across the industry
* Undergoes admin vetting

## Template Lifecycle

```
   draft ──► pending_approval ──► published ──► deprecated
     │              │                   │            │
     │              │                   │            │
     ▼              ▼                   ▼            ▼
  Initial       Awaiting          Live &         No longer
  creation      admin review      usable         recommended
```

### Status Definitions

| Status             | Description                | Can upload artifacts?          |
| ------------------ | -------------------------- | ------------------------------ |
| `draft`            | Template being created     | ❌ No                           |
| `pending_approval` | Submitted for admin review | ❌ No                           |
| `published`        | Approved and live          | ✅ Yes                          |
| `deprecated`       | No longer recommended      | ⚠️ Existing uploads still work |

## Admin Vetting Process

All new templates (especially shared ones) must be vetted by Docyard admins:

1. **Technical Review**
   * Are lock types properly structured?
   * Are validation rules correct?
   * Are data types appropriate?

2. **Business Review**
   * Does the template make business sense?
   * Is the name/description clear?
   * Could this be shared across distributors?

3. **Approval Decision**
   * **Approve**: Published to registry
   * **Reject**: Returned with feedback
   * **Request Changes**: Awaiting modifications

## Using Templates

When uploading an artifact, distributors:

1. Select a template from the registry
2. Fill in values for all required locks
3. Optionally adjust weights
4. Set the threshold score
5. Upload the content

```json theme={null}
POST /api/v1/upload/artifacts
{
  "template_id": "uuid-of-template",
  "locks": {
    "policy_number": { "value": "POL-12345678" },
    "effective_date": { "value": "2026-03-15" },
    "mortgagee_name": { "value": "FirstCity Bank" }
  },
  "threshold": 20,
  "content": "<file-data>"
}
```

## Artifact Types for Collectors

Collectors don't interact with templates directly. They see:

* **Artifact Type Name**: As metadata in search results
* **Lock Types**: As searchable/filterable fields
* **Document Type**: A system-level lock all artifacts must have

This helps collectors understand what they're retrieving without exposing template complexity.

***

## Next Steps

* Understand the [Lock-Key-Weight Model](/concepts/lock-key-weight)
* Learn about [Distributors](/concepts/distributors)
* See the [API Reference](/api-reference/artifact-types)