---
title: "ai.file@1 · OpenVibe.Services"
canonical: "https://openvibe.services/docs/contracts/ai.file"
updated: null
---

# ai.file@1 · OpenVibe.Services

HTML: [ai.file@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/ai.file)

# AiFile `ai.file@1`

Generated at 2026-11-13 06:25:48 UTC from [`openvibe-contracts v0.419.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.419.0) and [`openvibe-sdk v0.161.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/v0.161.0).

- Version: 1.0.0
- Owner: ai
- Visibility: first-party
- Status: active
- Compatibility: backward
- Schema: [`https://openvibe.network/contracts/ai/file.v1.json`](/docs/contracts/ai.file.json)

ai.file@1: a person attachment or model-produced artifact stored by Media. The reference is metadata only; file bytes are never embedded in an AI turn.

## Fields

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `id` | string | yes |  | - `minLength 1`<br>- `maxLength 200` |
| `name` | string | yes |  | - `minLength 1`<br>- `maxLength 255` |
| `media_type` | string | yes |  | - `minLength 1`<br>- `maxLength 255` |
| `size` | integer | yes |  | - `minimum 0` |
| `storage` | object | yes |  | - `no other fields` |
| `storage.provider` | const | yes |  | - `= "media"` |
| `storage.key` | string | yes |  | - `minLength 1`<br>- `maxLength 500` |
| `access` | object | yes |  | - `no other fields` |
| `access.readers` | array of string | yes |  | - `minItems 1`<br>- `unique items`<br>- `items: minLength 1`<br>- `items: maxLength 200` |
| `read` | one of | yes |  |  |
| `role` | enum |  |  | - `one of "input", "artifact"` |

## Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

 Valid: text-attachment

~~~~
{
  "id": "med_file_01",
  "name": "notes.txt",
  "media_type": "text/plain",
  "size": 12,
  "storage": {
    "provider": "media",
    "key": "files/usr_01/med_file_01"
  },
  "access": {
    "readers": [
      "usr_01"
    ]
  },
  "read": {
    "method": "text",
    "content": "hello world"
  },
  "role": "input"
}
~~~~

Rejected: inline-data

~~~~
{
  "id": "med_file_01",
  "name": "notes.txt",
  "media_type": "text/plain",
  "size": 12,
  "storage": {
    "provider": "media",
    "key": "files/usr_01/med_file_01"
  },
  "access": {
    "readers": [
      "usr_01"
    ]
  },
  "read": {
    "method": "text"
  },
  "bytes": "not allowed"
}
~~~~

## Validate

~~~~
const contracts = require('openvibe-contracts');
contracts.validate('ai.file@1', value);   // { valid, errors: [{ path, message }] }
~~~~