Socotra document templates: what it takes to change one line

Compliance wants one line reworded on the California wildfire notice before renewals go out. The notice lives in a Liquid template in a repository. So the fix needs an engineer, a pull request, a configuration deploy and a render check. The sentence itself takes nine seconds to write.

That gap, between the size of the change and the size of the process, is the whole subject of this post. It is not a complaint about Liquid, which is a good templating language, and it is not an argument that Socotra is a bad core platform. It is about who owns a policy document, and what it costs when the answer is "the engineering team."

How Socotra renders a policy document

Everything in this section comes from Socotra's own public documentation, because the mechanics are the argument and they are already published.

• Templates are HTML and CSS with embedded Liquid markup, in files named like *.template.liquid. Velocity is also supported for dynamic documents.
• Policy data is exposed through a structured snapshot, read with paths such as data.policy.characteristics[0].gross_premium.
• A Document Data Snapshot Plugin and Controlling Template Data rules decide what data a template can see.
• Static documents are pre-rendered attachments. Dynamic documents pass through a rendering step that fills the template from live policy data.
• Custom Liquid filters handle currency formatting, rate table lookups, timestamp formatting, and premium and commission maths.
• Conditional logic and loops come from Liquid or Velocity natively. There are reusable document snippets, document consolidation for merging several documents, and a Policy Document Selection Plugin that decides which document applies to which entity.

It is a capable system, and a team that is comfortable in a repository can do real work in it. Socotra's documentation also talks about streamlining the rendering feedback loop, and notes behaviour and limitations around consolidation, which tells you that iteration speed and edge cases are known friction rather than anything hidden.

Here is the shape of it. This snippet is representative, built from the documented data paths and filters rather than copied from any customer's configuration.

{% if data.policy.characteristics[0].state == "CA" %}
  <section class="notice">
    {% include "ca-wildfire-fair-plan-notice" %}
  </section>
{% endif %}

<p>
  Total premium:
  {{ data.policy.characteristics[0].gross_premium | format_currency }}
</p>

Read that as a compliance officer rather than as an engineer. The wording you are responsible for is inside a conditional, behind a path you cannot verify, in a file you cannot open. You can review a rendered PDF after the fact. You cannot author the sentence.

Why a homeowners packet is where this bites hardest

A single document in code is an inconvenience. A homeowners packet in code compounds, because the packet is not one document and its contents are not fixed.

A bound homeowners policy goes out as a declarations page, a base policy form such as an HO-3, whichever endorsements the insured selected, every notice the state mandates, a mortgagee copy when there is a mortgagee, and the NFIP or private flood forms when flood is bound. Which of those appear depends on the coverage, the property and the state.

So the rules multiply, and they are the kind of rules that change for reasons outside your release calendar:

• Include the California wildfire and FAIR Plan notice when the state is CA and the property sits in a very high fire-hazard zone.
• Include the NFIP flood form when the flood zone is A or V.
• Attach water back-up HO 04 95 only when the insured selected it.
• Attach ordinance or law HO 04 77 and scheduled property HO 04 61 on the same basis.
• Add the mortgagee notice only when a mortgagee is present.

A state changes a disclosure. Every template on the shared drive is quietly out of date.

Then multiply again by lifecycle. The declaration packet is one set. A midterm endorsement produces a change endorsement, a revised declarations page, a coverage-reducing-endorsement explanation where one applies, and a mortgagee notice. Cancellation and nonrenewal produce their own notices, with the notice period and the wording driven by state. Same insured, same policy, same underlying data, three different document sets, and in a code-templated world three more sets of files to keep in sync.

The part that is not a Liquid problem

Worth being precise here, because the honest version of this argument is narrower than the marketing version.

Liquid and Velocity are mature, well documented and free. Nobody needs a better templating language. The problem is not the syntax, it is that a policy document is a compliance artifact whose authors are compliance and operations people, and storing it as source code puts it permanently out of their reach. Every edit becomes a deploy. Every deploy needs an engineer. The person accountable for the wording is the one person who cannot change it.

That is a question about ownership and release cadence, not about template engines, and it is the reason the document layer is often the first thing teams pull out of a core platform.

What moving the document layer out looks like

The realistic version of this is not a migration off Socotra. It is narrower: the core platform keeps being the system of record, and document generation becomes a service it calls.

1. Map the data the templates already consume

The template is already reading a known set of paths. Map each one to a field alias, so data.policy.characteristics[0].gross_premium becomes gross_premium. This step is mechanical and it is also the step that tells you how many fields the packet truly depends on, which is usually fewer than the repository suggests.

2. Rebuild each template in an editor instead of a file

Paste the structure, replace Liquid variable tags with variable chips, and replace {% if %} and {% for %} with IF/ELSE and FOR EACH blocks. For fixed carrier PDFs, do not re-flow the HTML at all: use a fillable template and map typed fields onto the PDF you are already licensed to use.

3. Put the inclusion rules on the packet, not inside the documents

Each document in a workflow carries its own include or exclude expression, so the CA wildfire notice rule lives on the notice rather than being buried in a conditional inside a larger template. Fields declared at the workflow level are entered once and map into every document that needs them, which is what stops the same insured detail being retyped across the dec page, the binder and the certificate.

4. Keep the core system as the system of record

Socotra, or any other policy admin system, POSTs the policy JSON and gets the assembled packet back. The document service never owns policy data. There is no re-platforming, and no data migration, because there is no second system of record.

5. Use environments and versions for the release part

Each template and workflow has its own published version per environment. Validate in staging, pin production, roll back a document without rolling back a platform deploy. The point is that the document release stops being coupled to the application release.

What this does not solve

Three things to be straight about, because they decide whether any of the above is relevant to you.

• Mezdoc is a document generation, assembly and signature layer. It is not a core platform, a rating engine or an underwriting system. Moving documents out moves documents, nothing else.
• There is no automatic Liquid or Velocity importer today. Migrating a template is a manual rebuild, which means the work is real and proportional to how many templates you have.
• If your documents are stable, your template count is small, and your engineers do not mind the requests, none of this is worth doing. The cost of this change is paid up front.

When it is worth doing

The pattern that justifies it looks like this: a packet whose contents vary by state and coverage, several lifecycle document sets that share the same fields, notices that change on a regulator's calendar instead of yours, and a compliance team that currently files tickets to reword sentences. The more of those are true at once, the more the document layer is doing work that does not belong in a repository.

If that is the shape of your problem, the document layer page has the full mapping table, every template construct and what replaces it. The homeowners and flood page walks through the same packet with the real form numbers and conditions, and the API reference shows exactly what your core system would POST.