Data Specifications

Manage the reusable data routing rules that power document template generation.

Quickstart

Navigate to Settings > Data Specifications to define the data traversal rules that connect your document templates and data dictionaries to the rest of the Servantium database.

In-Depth

Data Specifications (Data Specs) act as the instruction manual for the document generation engine and dynamic schema formulas. While a document template handles the visual layout (HTML or DOCX), the Data Spec dictates exactly which database records to fetch and how to structure them for merging.

Because Data Specs are standalone entities, you can build a single complex routing rule (e.g., “Full Quote with Account and Resource Plans”) and share it across multiple document templates or Data Dictionaries. If you update a Data Spec’s base entity, the backend automatically cascades the target collection updates to all linked entities to ensure your generation routing remains valid.

Anatomy of a Data Spec

A Data Spec is composed of two primary elements:

  • Base Entity: The primary root record this specification is executed from. For example, if you generate the document from an engagement, the base entity is engagement. If you generate it directly from a quote, the base entity is quote.
  • Data Sources: The traversal paths used to fetch related data outward from the base entity. Supported data source types include:
    • Document: Fetches a specific record by its exact path. It can also represent the generated document instance itself (using the documents collection), allowing you to define a defaults dictionary to automatically pre-seed custom properties (like document_type or requires_signature) when the document is created. These default values support dynamic Jinja tags, allowing you to populate properties using data from your merge payload. The system automatically validates these default fields against your organization’s documents Data Dictionary.
    • Reference: Fetches a foreign document linked by a field (e.g., pulling the account linked to an engagement).
    • Subcollection: Queries and aggregates all child records (e.g., project_plan_items). Subcollections are fetched in bulk; all filtering and sorting must be handled at the template layer.
    • Alias: Creates a semantic pointer to another data source for cleaner template tags.
    • Parent: Fetches a parent or ancestor document by traversing upward from the target entity’s path. You can specify the exact hierarchy level to traverse (e.g., 1 for immediate parent, 2 for grandparent) or target a specific ancestor collection (like quotes or engagements). Advanced configurations allow you to optionally set a starting source (from_source), define a specialized handler, and provide JSON-formatted default values with inline syntax validation.
Note

Data Specs are also used by Data Dictionaries to resolve cross-collection variables for Formula properties. The backend automatically prunes the Spec to fetch only the required data sources for the expression.

Creating and Editing

  1. Navigate to Settings > Data Specifications.
  2. Click the Add (plus) icon to create a new specification.
  3. Provide a clear Name (e.g., “Standard Project Plan Spec”).
  4. Use the visual editor to define your base entity and data sources, or switch to the Raw JSON tab to write the schema manually. If no data sources are defined, an empty state card guides you to select a preset or add your first data source.
  5. To remove a data source, click the delete icon on its row. A confirmation dialog will prompt you to confirm, ensuring the data source is cleanly purged from your specification.
  6. Once saved, navigate to any Document Template and link the Data Spec via the template’s details form.
Tip

If you are unsure how to structure a Data Spec, the visual editor provides built-in standard presets (like “Quote Standard” or “Engagement Standard”) that instantly populate the most common data sources.

AI Generation

You do not have to write Data Specs manually. Click the AI generate button (sparkle icon) in the header of any Data Spec workspace. Provide natural language instructions describing what data you need, and the dedicated Data Spec QA Agent will automatically build the base entity and define all necessary traversal paths.

During generation, the AI automatically scans your organization for existing Data Specs that match the required base entity. If a matching specification already exists, the AI actively reuses it to prevent duplicate schemas and maintain a clean, centralized data architecture.

Need more help?

Our support team is available to assist you.

Contact Support