Spec v0.1 — draft
Canonical Slot Vocabulary
The canonical-slot vocabulary is the IDP-/SoR-neutral namespace Govern uses to refer to fields on legal-domain entities. A slot key like matter.responsible_attorney names what the value means without committing to any particular system-of-record’s column name, field ID, or wire format.
This document is the published taxonomy. It is the contract between skill authors, connector authors, external auditors, and firm admins.
Capability tiers
| Tier | Description |
|---|---|
observation-only | Read access only. No writes. Used for evidence-gathering and matter-context resolution. |
mediated-write | Writes gated by Govern policy. Default tier for entity mutations. |
mediated-write-financial | Mediated-write plus explicit per-firm grant for financial-truth slots. |
Status legend
- active — Used by at least one v1 write tool today. Stable; rename is a breaking change to skill authors.
- catalog — Defined for completeness; not yet referenced by a v1 write tool. Renames safe pre-spec-v1.
Matter slots (35)
The unit of legal work. Has a responsible attorney, a client, and a billing relationship.
| Slot | Status | Tier | Description |
|---|---|---|---|
| matter.name | active | mediated-write | Matter display name (typically matter number + style) |
| matter.matter_number | active | mediated-write | Firm-assigned human-readable matter identifier (e.g., 2026-0142) |
| matter.matter_hash_number | catalog | mediated-write | SoR-assigned accession code (the SoR-internal short ID) |
| matter.client | active | mediated-write | Lookup to the matter's client contact |
| matter.status | active | mediated-write | Open / closed / on-hold / etc. — values controlled by firm picklist |
| matter.practice_area | active | mediated-write | Practice-area picklist (litigation, transactional, IP, …) |
| matter.responsible_attorney | active | mediated-write | Lookup to the user record of the attorney who owns the matter |
| matter.billing_partner | catalog | mediated-write | Lookup to the partner who signs off on bills |
| matter.paralegal | catalog | mediated-write | Lookup to the assigned paralegal |
| matter.associate | catalog | mediated-write | Lookup to the assigned associate |
| matter.admin | catalog | mediated-write | Lookup to the matter administrator |
| matter.other_staff | catalog | mediated-write | Multi-lookup for additional staff |
| matter.matter_open_date | active | mediated-write | Date the matter was opened |
| matter.matter_close_date | active | mediated-write | Date the matter was closed (null while open) |
| matter.claim_number | catalog | mediated-write | Insurance claim number (insurance-defense practice) |
| matter.claim_representative | catalog | mediated-write | Insurance claim rep contact |
| matter.client_matter_id | catalog | mediated-write | Client's internal matter ID for cross-reference |
| matter.state_code | active | mediated-write | Two-letter state/jurisdiction code |
| matter.referral_source | catalog | mediated-write | Lookup to the referring contact |
| matter.referral_source_text | catalog | mediated-write | Free-text referral source when no contact is linked |
| matter.referral_type | catalog | mediated-write | Referral category (web, peer, prior client, …) |
| matter.primary_email | catalog | mediated-write | Primary email for matter correspondence |
| matter.phone | catalog | mediated-write | Primary phone |
| matter.bill_to_email_address_s | catalog | mediated-write-financial | Bill-to email override(s) |
| matter.bill_to_contact_name | catalog | mediated-write-financial | Bill-to contact name override |
| matter.bill_to_address | catalog | mediated-write-financial | Bill-to address override |
| matter.trust_balance | catalog | observation-only | Read-only trust account balance. Writing direct trust ledgers is out of scope for v1. |
| matter.last_bill | catalog | observation-only | Date of most recent issued bill |
| matter.last_payment | catalog | observation-only | Date of most recent payment received |
| matter.lifetime_fees_received | catalog | observation-only | Computed lifetime fees received |
| matter.detailed_description | active | mediated-write | Full matter description |
| matter.short_description | active | mediated-write | Short summary |
| matter.quick_notes | active | mediated-write | Inline notes field |
| matter.conflict_check | catalog | mediated-write | Conflict-check status / outcome |
| matter.calendar_toolset_ref | catalog | mediated-write | Calendar/court-rules integration toolset reference |
Contact slots (25)
Includes both client contacts and non-client parties (opposing counsel, witnesses, etc.).
| Slot | Status | Tier | Description |
|---|---|---|---|
| contact.name | active | mediated-write | Display name |
| contact.first_name | active | mediated-write | Given name |
| contact.last_name | active | mediated-write | Family name |
| contact.middle_name | active | mediated-write | Middle name |
| contact.prefix | catalog | mediated-write | Salutation prefix (Dr., Mr., …) |
| contact.suffix | catalog | mediated-write | Suffix (Jr., III, Esq., …) |
| contact.title | active | mediated-write | Job title |
| contact.company | active | mediated-write | Company name |
| contact.is_client | active | mediated-write | Bool — is this contact a current client? |
| contact.contact_type | active | mediated-write | Type picklist (client, opposing party, witness, …) |
| contact.contact_status | active | mediated-write | Status picklist (active, inactive, …) |
| contact.primary_email | active | mediated-write | Primary email |
| contact.alternate_email | active | mediated-write | Secondary email |
| contact.work_phone | active | mediated-write | Work phone |
| contact.mobile_phone | active | mediated-write | Mobile phone |
| contact.home_phone | active | mediated-write | Home phone |
| contact.business_address | active | mediated-write | Business address |
| contact.home_address | active | mediated-write | Home address |
| contact.date_of_birth | catalog | mediated-write | DOB (PII; redacted in audit feed by default) |
| contact.social_sec | catalog | mediated-write | SSN (PII; redacted in audit feed by default) |
| contact.bill_to_email_address_s | catalog | mediated-write-financial | Bill-to email override(s) |
| contact.accounting_external_id | catalog | observation-only | External accounting-system row ID |
| contact.accounting_realm | catalog | observation-only | External accounting-system realm/tenant |
| contact.accounting_sync_token | catalog | observation-only | External accounting sync token |
| contact.accounting_last_synced | catalog | observation-only | External accounting last-synced timestamp |
PNC slots (19)
Prospective New Client — pre-engagement intake record. Becomes a contact + matter at conversion. Other systems call this a “lead” or “prospect”; the pnc. prefix is a candidate for rename to lead. in v2 once a non-CB connector concretely needs it.
| Slot | Status | Tier | Description |
|---|---|---|---|
| pnc.name | active | mediated-write | Display name |
| pnc.first_name | active | mediated-write | Given name |
| pnc.last_name | active | mediated-write | Family name |
| pnc.company | active | mediated-write | Company |
| pnc.primary_email | active | mediated-write | Primary email |
| pnc.work_phone | active | mediated-write | Work phone |
| pnc.source | active | mediated-write | Source picklist (referral, web, walk-in, …) |
| pnc.status | active | mediated-write | Status picklist (new, contacted, qualified, …) |
| pnc.description | active | mediated-write | Full intake description |
| pnc.intake_notes | active | mediated-write | Intake notes |
| pnc.responsible_attorney | catalog | mediated-write | Lookup to assigned attorney |
| pnc.practice_areas | catalog | mediated-write | Multi-picklist of relevant practice areas |
| pnc.conflict_check | catalog | mediated-write | Conflict-check status |
| pnc.conflict_status | catalog | mediated-write | Conflict-check outcome |
| pnc.expense_budget | catalog | mediated-write-financial | Anticipated matter expense budget |
| pnc.matter | catalog | observation-only | Lookup to converted matter (post-conversion) |
| pnc.contact | catalog | observation-only | Lookup to converted contact (post-conversion) |
| pnc.referral_direction | catalog | observation-only | Referral direction (sent / received) |
| pnc.consultation_complete | catalog | observation-only | Bool — consultation activity complete |
Billing-entry slots (27)
Time entries, hard-cost expenses, and AI-spend pass-throughs. Write slots require mediated-write-financial; a small number of post-issuance fields are observation-only. These are catalog-only for v1 — the billing-entry write tools reference field IDs directly today. They migrate to slot-resolved writes in Workstream A.2.
| Slot | Status | Tier | Description |
|---|---|---|---|
| billing_entry.name | catalog | mediated-write-financial | Display name |
| billing_entry.description | catalog | mediated-write-financial | Bill narrative |
| billing_entry.matter | catalog | mediated-write-financial | Lookup to matter |
| billing_entry.billing_code | catalog | mediated-write-financial | Lookup to billing code (UTBMS task code, AI-vendor code, …) |
| billing_entry.timekeeper | catalog | mediated-write-financial | Lookup to timekeeper |
| billing_entry.entry_date | catalog | mediated-write-financial | Service date |
| billing_entry.billable_hours | catalog | mediated-write-financial | Hours billed (time entries) |
| billing_entry.billable_rate | catalog | mediated-write-financial | Rate at which hours are billed |
| billing_entry.billable_value | catalog | mediated-write-financial | Computed billable amount |
| billing_entry.actual_hours | catalog | mediated-write-financial | Hours worked (may differ from billable) |
| billing_entry.total_amount | catalog | mediated-write-financial | Total amount (post-tax / post-discount) |
| billing_entry.is_non_billable | catalog | mediated-write-financial | Bool — flag as non-billable |
| billing_entry.hide_from_bill | catalog | mediated-write-financial | Bool — hide from rendered bill |
| billing_entry.notes | catalog | mediated-write-financial | Internal notes |
| billing_entry.type | catalog | mediated-write-financial | Entry type discriminator (time / expense / flat) |
| billing_entry.account | catalog | mediated-write-financial | GL account |
| billing_entry.payee | catalog | mediated-write-financial | Lookup to payee (for hard-cost expenses) |
| billing_entry.vendor | catalog | mediated-write-financial | Lookup to vendor record |
| billing_entry.secondary_billing_code | catalog | mediated-write-financial | Secondary billing-code lookup |
| billing_entry.write_down_value | catalog | mediated-write-financial | Write-down amount (negative adjustment) |
| billing_entry.split_billing_percentage | catalog | mediated-write-financial | Split-billing percentage |
| billing_entry.time_discount | catalog | mediated-write-financial | Time-entry discount amount |
| billing_entry.time_flag | catalog | mediated-write-financial | Time-entry flag column |
| billing_entry.bill | catalog | observation-only | Lookup to issued bill (post-issuance audit only) |
| billing_entry.accounting_external_id | catalog | observation-only | External accounting-system row ID |
| billing_entry.accounting_realm | catalog | observation-only | External accounting realm/tenant |
| billing_entry.accounting_sync_token | catalog | observation-only | External accounting sync token |
Override semantics
The slot resolver runs in priority order:
- Per-firm override in the firm’s canonical-slot table (set via
/admin/fields/slotsor the divergence-detection wizard). - Connector catalog default — the connector’s own
CATALOG_DEFAULTSmap.
A connector that does not support a slot declares null. Tools attempting to read or write a null slot receive a structured slot_unavailable error from the policy engine, not a runtime adapter failure.
How this vocabulary evolves
core.* slot keys are append-only after v1.0. Renames require a major version bump. To propose a new slot, open a PR adding a row to the appropriate entity table with catalog status. Mark active only when at least one v1 write tool references it.