Attributes

Overview

Attributes are structured metadata fields used to describe, classify, search, route, report on, and control access to documents. They are better suited than free-form tags when the value has business meaning, needs validation, drives automation, or should be used consistently across a site.

Examples:

• documentType = invoice
• invoiceNumber = 1042
• department = Finance
• confidentiality = Restricted
• status = Approved
• retentionCategory = financial-record

Attributes are commonly used with Documents, Schemas, Search, Rulesets, Workflows, and Security.

Attribute Definitions vs Document Attributes

There are two related concepts:

Concept	What it means	Example API area
Attribute definition	A reusable field definition available within a site. It describes the attribute key, data type, and behavior.	/attributes
Document attribute	A specific value attached to a specific document.	/documents/{documentId}/attributes

Think of an attribute definition as the field setup, and a document attribute as the value stored on an individual document.

Example:

Level	Example
Attribute definition	department is a STRING attribute available for the site.
Document attribute	Document abc123 has department = Finance.

Attribute Data Model

An attribute is described by three main pieces:

Field	Purpose
key	The attribute name, such as department, invoiceNumber, or status.
dataType	The kind of value the attribute stores.
type	The attribute's permission or system behavior, such as STANDARD, GOVERNANCE, or OPA-related access use.

Document attribute values can be single-value or multi-value depending on the API shape and schema rules used by the site.

Value Types and Special Types

FormKiQ supports standard value types and special-purpose attribute types.

Value Types

Data type	Use for	Example
STRING	Text values, categories, identifiers, names, status values, and dates stored as strings.	department = Finance
NUMBER	Numeric values used for sorting, filtering, comparison, reporting, or calculations.	invoiceTotal = 1250.75
BOOLEAN	True/false values.	isApproved = true

Special Types

Data type	Use for
KEY_ONLY	Identifier-only attributes where the presence of the key is meaningful.
PUBLICATION	Publication-related attributes for document review and publishing processes.
RELATIONSHIP	Relationships between documents, such as attachments or renditions.
WATERMARK	Watermark configuration that can be attached to documents.

For document relationship examples, see Documents.

Attribute Types

FormKiQ supports several attribute behavior types:

Type	Purpose
STANDARD	General-purpose attributes used for classification, search, reporting, workflows, and integrations.
GOVERNANCE	Attributes that require GOVERN or ADMIN permissions to add, update, or delete.
OPA access attributes	Attributes used by Open Policy Agent policies for attribute-based access control.

Use GOVERNANCE attributes for metadata that should be controlled by data governance or records-management roles. Use OPA-related access attributes when document metadata should influence access decisions.

For access-control details, see Security and Open Policy Agent.

Common Use Cases

Classification

Attributes can classify documents by type, department, region, owner, customer, or business process.

Examples:

• documentType = contract
• department = Legal
• region = EMEA
• customerId = acme

Search and Filtering

Attributes make document search more precise than filename or full-text search alone.

Examples:

• Find invoices where vendor = Acme.
• Find contracts where renewalDate is within a date range.
• Find HR documents where employeeId = 12345.
• Find records where confidentiality = Restricted.

For search behavior, see Search.

Workflow Routing

Attributes can drive workflow and ruleset decisions.

Examples:

• Route invoiceTotal > 10000 to a senior approver.
• Move status = Approved documents to a publication workflow.
• Trigger review when retentionCategory = legal-hold.
• Send documents from department = Finance to a finance queue.

For automation details, see Rulesets and Workflows.

Governance and Access Control

Attributes can help enforce governance and access policies.

Examples:

• Use confidentiality = Restricted for sensitive records.
• Use owner = username for owner-only access patterns.
• Use retentionCategory to support retention review.
• Use classification attributes to drive OPA access policies.

For access control, see Security.

Reporting and Analytics

Attributes are useful dimensions for reporting.

Examples:

• Documents by department
• Documents by document type
• Documents missing required metadata
• Documents by status or workflow stage
• Records by retention category

For reporting patterns, see Reporting, Analytics, and Audit.

Schemas, Classifications, and Allowed Values

Attributes become more powerful when combined with schemas and classifications.

Feature	How it relates to attributes
Site schema	Defines required and optional attributes for a site.
Classification	Defines required and optional attributes for a document class.
Allowed values	Restricts an attribute to approved values.
Composite keys	Supports efficient searching across multiple attributes.
Localized allowed values	Supports display values in different locales where configured.

Use schemas when you need consistency. Use classifications when different document types require different metadata rules.

Examples:

• Invoice documents require invoiceNumber, vendor, and invoiceDate.
• Contract documents require counterparty, effectiveDate, and renewalDate.
• Employee records require employeeId, recordType, and department.

For details, see Schemas and Locales.

Reserved Attribute Keys

Some attribute keys are reserved for FormKiQ system use. Avoid using these keys for custom business metadata.

Reserved key	Purpose
Classification	Used for document classification.
Relationships	Used to manage document relationships.
MalwareScanResult	Stores malware scan results.
EsignatureDocusignEnvelopeId	Tracks DocuSign envelope IDs.
EsignatureDocusignStatus	Tracks DocuSign signature status.

Watermark Attributes

WATERMARK attributes define watermark settings that can be applied to documents. A watermark can include text, image reference, position, rotation, and scale settings.

Common use cases:

• Add CONFIDENTIAL to sensitive records.
• Add DRAFT to documents under review.
• Add a company logo or brand mark.
• Apply visual status indicators before external distribution.

Watermark configuration can include:

Property	Purpose
text	Watermark text to display, such as CONFIDENTIAL or DRAFT.
rotation	Rotation angle.
imageDocumentId	Document ID of an image to use as a watermark.
scale	Scale behavior, such as BEST_FIT or ORIGINAL.
position	Anchor and offset settings for placement.

Example attribute definition:

{
  "key": "WATERMARK_SETTING",
  "dataType": "WATERMARK",
  "watermark": {
    "text": "CONFIDENTIAL"
  }
}

Best Practices

Naming

Use clear, stable names that will still make sense as the system grows.

Good examples:

• invoiceNumber
• clientName
• projectDeadline
• approvalStatus
• retentionCategory

Avoid unclear abbreviations, special characters, and names that are tied too tightly to one year or temporary project.

Use one naming convention consistently. camelCase is a practical default for custom attributes. FormKiQ reserved keys use PascalCase, such as Classification.

Data Type Selection

Choose data types based on how the value will be searched, validated, sorted, and reported.

Need	Recommended type
Category, status, owner, department, region	STRING
Amount, score, count, duration, timestamp number	NUMBER
Yes/no or enabled/disabled state	BOOLEAN
Presence-only flag	KEY_ONLY
Document relationship	RELATIONSHIP

For dates, choose a consistent representation before production. ISO 8601 strings are readable, while numeric timestamps can be useful for range queries and reporting.

Organization

Design attributes as a small data model, not as one-off labels.

Recommended practices:

• Maintain a data dictionary for important attributes.
• Define allowed values for controlled fields such as department, region, document type, and status.
• Use schemas or classifications for required metadata.
• Avoid duplicate meanings, such as both client and customerName unless the difference is intentional.
• Prefer stable identifiers, such as customerId, when names may change.
• Use composite keys when multi-attribute search performance matters.

Governance

Use controlled attributes for metadata that affects compliance, access, retention, or business process outcomes.

Examples:

• confidentiality
• retentionCategory
• legalHold
• recordType
• owner
• approvalStatus

Review governance attributes before changing names, allowed values, or schema rules because downstream workflows, searches, reports, and access policies may depend on them.

API Endpoints

Use the generated API reference for exact request and response schemas.

Attribute Definition Operations

Operation	Purpose	API reference
List attributes	Retrieve attribute definitions available for a site.	GET /attributes
Add attribute	Create a new attribute definition.	POST /attributes
Get attribute	Retrieve a specific attribute definition.	GET /attributes/{key}
Update attribute	Update an existing attribute definition.	PATCH /attributes/{key}
Delete attribute	Delete an attribute definition.	DELETE /attributes/{key}
Get allowed values	Retrieve allowed values for an attribute.	GET /attributes/{key}/allowedValues

Document Attribute Operations

Operation	Purpose	API reference
Add document attributes	Add multiple attributes to a document.	POST /documents/{documentId}/attributes
Set document attributes	Set or replace document attributes.	PUT /documents/{documentId}/attributes
Get document attributes	Retrieve all attributes for a document.	GET /documents/{documentId}/attributes
Get document attribute	Retrieve one document attribute by key.	GET /documents/{documentId}/attributes/{attributeKey}
Set document attribute value	Set a specific attribute value.	PUT /documents/{documentId}/attributes/{attributeKey}/value
Delete document attribute	Delete an attribute from a document.	DELETE /documents/{documentId}/attributes/{attributeKey}
Delete document attribute value	Delete one value from a multi-value attribute.	DELETE /documents/{documentId}/attributes/{attributeKey}/value

Schema and Classification Operations

Operation	Purpose	API reference
Get site schema	Retrieve the site schema.	GET /sites/{siteId}/schema
Set site schema	Create or update the site schema.	PUT /sites/{siteId}/schema
Get schema allowed values	Retrieve schema allowed values for an attribute.	GET /sites/{siteId}/schema/document/attributes/{key}/allowedValues
List classifications	Retrieve site classifications.	GET /sites/{siteId}/classifications
Add classification	Create a classification.	POST /sites/{siteId}/classifications
Get classification	Retrieve a classification.	GET /sites/{siteId}/classifications/{classificationId}
Set classification	Update a classification.	PUT /sites/{siteId}/classifications/{classificationId}
Delete classification	Delete a classification.	DELETE /sites/{siteId}/classifications/{classificationId}
Get classification allowed values	Retrieve allowed values for a classification attribute.	GET /sites/{siteId}/classifications/{classificationId}/attributes/{key}/allowedValues

Where to Go Next

• Documents
• Document Attributes API Tutorial
• Schemas
• Search
• Rulesets
• Workflows
• Security
• Open Policy Agent