FileMaker 2026 adds a new box to a field's advanced options, and it took me a while to fully grasp what it was really for. It isn't a new comment, and it isn't contextual help for your fellow developers: it's documentation that speaks only to an AI model, and it is of absolutely no use as long as you don't use any AI feature in your database. Here is what I've understood about it, with concrete examples.

A separate box, not to be confused with the usual comment

In our team, every field already carries a comment (I talked about this in my article on naming conventions). FileMaker 2026 adds a separate entry, under the Advanced button of the Fields dialog box: an option to add an annotation in the data definition language (DDL) (Claris — Options avancées de rubrique). DDL is the language used to describe the structure of a database. Whatever you type in this box is automatically injected into the DDL that FileMaker sends to an AI model when a step such as "Perform SQL Query by Natural Language" or "Perform Find by Natural Language" needs to understand your schema (Claris — Meilleures pratiques pour le schéma de base de données avec la génération de requêtes DDL et SQL).

 

Advanced field options dialog in FileMaker 2026, with the DDL annotation box filled in for the EstFacture field

 

Let's take an example I often give my teams: a field called EstTermine ("IsFinished"), a 0-or-1 boolean (with an auto-enter calculation, GetAsBoolean ( Self ), replacing the value so that a true boolean is always stored). If a user types "show me the unfinished files" into a natural-language find, the model only sees a number field named EstTermine — nothing tells it what 0 or 1 means. With the annotation "Boolean, 1 = file closed, 0 = file in progress, set automatically by the closing script", the model can correctly translate the question into a query on EstTermine = 0.

The trap to know before you start: it's all or nothing, per table

This is the most important technical point, and the one that surprised me the most when testing the feature: as soon as a single field in a table receives an annotation, the DDL generated for that table only contains the annotated fields. All the others simply disappear from what the AI model sees for that table (Claris — Meilleures pratiques pour le schéma de base de données avec la génération de requêtes DDL et SQL).

In practice, you can't annotate "as you go", one field here and there, telling yourself you'll finish later. Starting to annotate a table is a real decision: you have to cover every field the AI must keep seeing, or you'll make them invisible as a side effect. So it's a big job for a database that will be handed over to an AI — and a pointless one in every other case (in other words, for now, most cases).

What's worth annotating, and how to write a good annotation

In practice, I don't recommend annotating every field in a table. I start with the ones that are actually exposed to an AI query — fields shown on layouts or exposed through an API, non-obvious foreign keys, calculation fields displayed on screen, flags and statuses whose value isn't self-explanatory. Standard audit fields or already-clear text fields can wait, and temporary global variables are generally not worth exposing at all.

Two examples that come up often in our work, in addition to EstTermine:

  • A foreign key such as IdContact in an Addresses table. In our team, an identifier always keeps the same name from one table to another, which is very readable for a developer who knows the convention, but remains ambiguous for a model discovering the schema cold: is it the row's own identifier, or a reference to another table? An annotation such as "Foreign key to Contacts, a contact can have several addresses" removes the ambiguity immediately.
  • A value list such as Statut (Brouillon, Validé, Annulé — Draft, Approved, Cancelled). Without an annotation, the model has to guess the exact value to compare against, with the risk of getting the case or the word wrong. "Valid values: Brouillon, Validé, Annulé" removes the guesswork.

You can reuse your existing comments

For a database already well documented with classic field comments, there is a handy shortcut: according to Claris, if an annotation is empty and the comment starts with the special tag [LLM], the comment text (without the tag) is used in the DDL as if it were an annotation (Claris — Meilleures pratiques pour le schéma de base de données avec la génération de requêtes DDL et SQL). It saves you from retyping everything to test the feature on an older database, and it's a good way to get a first impression before switching properly to dedicated annotations.

Key takeaways

The DDL annotation is not a new commenting best practice to roll out everywhere: it is targeted documentation, written solely so that an AI model correctly interprets your schema when a FileMaker AI feature (or a custom script) needs it. The main trap to avoid is the all-or-nothing behaviour per table, and the best strategy remains to annotate only what will actually be exposed to an AI query — not the whole database. For a team that already comments its fields systematically, as we do, it's an extension at almost no cost rather than a new project.

I encourage you to read Claris's help pages on this feature, which are well written.

Sources

A question? A project to study?

20 - 6 =
hCaptcha *

Contact us

Please complete the form.
See our Contact page to contact us directly. 

Logo Claris Partner

Logo Claris MarketPlace

Logo Claris Partner Reseller

Copyright ©2020-2026 IU-DATA | All rights reserved | Legal Notices | Privacy Policy | Terms and Conditions | Designed by inPhobulle