Files and artifacts in fields
A file field holds a file, not a string of characters. The field stores the id of an artifact, and the artifact store keeps the bytes outside the document. This keeps documents small and lets two documents share one file without copying it.
When to use this
Section titled “When to use this”Use a file field when the file is part of the record: a signed contract on a deal, a resume on a candidate, a photo on an item. For discussion files that belong to no field, use the attachments panel instead (see Sidecars (comments, attachments)).
Before you start
Section titled “Before you start”- Storage is built in. The artifact store exists on every instance. You declare the field; you do not configure storage.
- A size limit. One upload is limited to 50 megabytes by default. Your administrator sets the limit.
- A type list, if you want one. Facet accepts any file type by default. Declare an
acceptlist when the field should take only some types.
1. Declare the file field
Section titled “1. Declare the file field”"contract": { "type": "file", "accept": ["application/pdf"], "title": "Signed contract"}The accept list uses MIME types. Facet decides the type of an upload from the file content, not from the file name, and rejects an upload that does not match the list. A field without accept takes every type.
2. Upload in the app
Section titled “2. Upload in the app”In a form, the user picks a file for the field. Facet uploads the bytes, stores them, and puts the artifact id into the field. The save and the upload are one step: if either fails, nothing is written.
3. Upload through the API
Section titled “3. Upload through the API”Send a multipart body. One part named $content carries the document fields, and one part per file field carries the bytes, named after the field.
curl -k -X POST "https://facet.localhost:3443/Api/projects/Deliverable" \ -H "Authorization: Bearer $FACET_API_KEY" \ -F '$content={"title":"Kickoff deck"}' \ -F 'contract=@./kickoff.pdf'-k skips the certificate check of the local development address.
4. Know what the store does
Section titled “4. Know what the store does”| Rule | Effect |
|---|---|
| Same content, one copy | Identical bytes are stored once and reused. |
| Access follows documents | A file is readable through the documents that reference it. |
| Out-of-band uploads | A file pasted into a long text is uploaded first and linked on save. |
A longtext field can embed a file link with the form urn:facet:artifact:<id>. Every reader of that document gains access to the file.
Example
Section titled “Example”{ "domain": "projects", "doctype": "Deliverable", "aggregate_root": true, "schema_version": 1, "display_name": "{{ title }}", "fields": { "title": { "type": "string", "required": true, "filters": ["equality", "text_search"] }, "contract": { "type": "file", "accept": ["application/pdf"] }, "deck": { "type": "file" } }}The contract field takes only PDF files. The deck field takes any file type.
Troubleshooting
Section titled “Troubleshooting”The upload answers 413
Section titled “The upload answers 413”The file is larger than the size limit. Use a smaller file, or ask your administrator to raise the limit.
The upload answers 422 with a MIME error
Section titled “The upload answers 422 with a MIME error”The file content does not match the accept list. Rename the field list or convert the file; changing the file name alone does not help, because Facet reads the content.
An export carries a short id instead of the file
Section titled “An export carries a short id instead of the file”That is the artifact id. The file content does not travel with a CSV or JSON export; download files from the document page.
A file link in a document shows as dead
Section titled “A file link in a document shows as dead”The file was destroyed by an administrator. The reference stays in the text but the bytes are gone.
Related
Section titled “Related”- Artifacts (engineering doc) — the artifact store in full.
- Domains and isolation — how the store sits outside your domain.
- Secret and write-only fields — store credentials safely in fields.