Basic Clause Author Tutorial

Part 2: Introduction to the ClauseBase grammar

Before we can really start drafting clauses, you have to learn a few more elements about the “special grammar” of the words you put inside the clauses. While the bulk of your clauses will consist of regular words (similar to clauses in MS Word), the special grammar allows you to make clauses intelligent.

For an overview of all the symbols you can use and options available to you when working with the special grammar, take a look at the ClauseBase Grammar Sheet. Open it now and save in a convenient place or print it out. For information on how to type these symbols on your keyboard, check out our overview of the keyboard shortcuts for special symbols.

Referring to concepts

In MS Word, you would write “The Employee shall securely store Confidential Information”.

In ClauseBase, you would instead write “#Employee shall securely store #confidential-information”:

  • all articles must be removed (a / an / the in English, or le / la / les / un / une / des in French)
  • all capitals must be removed, except for the first word of each sentence
  • a hash-tag(#) must be inserted before the concept

This one-time clean-up is necessary, because you do not know upfront which concept labels and styling will be chosen by the user. At the moment that a document is shown on the screen, the concept labels, capitals and articles will be applied by ClauseBase, depending on the user’s settings. Accordingly, a single sentence may end up quite differently — for example:

  • The Worker shall securely store Confidential Information.
  • THE EMPLOYEE shall securely store SENSITIVE DATA.
  • Jean Janson shall securely store the confidential information.

Cross-references

In MS Word, you would write “The employee will comply with the internal rules set forth in clause 5.4”. If you want this clause to be reusable, you can obviously not use such hard-coded cross-references, because clause 5.4 may end up being clause 27 in some other contract.

Instead, you would write “… set forth in §#internal-rules”. ClauseBase will then dynamically search for a clause that claims to implement the concept #internal-rules, and insert its actual number. If such clause does not yet exist, then an error message is inserted.

For more information on creating cross-references, click here.

Conjugations

The user of a clause can freely choose concept labels — so #employees may get replaced by “staff”, while #employeur may get replaced by “la Société”. Naturally, this also means that some verbs, adjectives and pronouns (him, herself, their, …) that relate to these concepts, may need to be updated.

To do so, you should enclose such words in <angular brackets>. For example:

Traditional approach in WordDynamic approach in ClauseBase
if employer terminates the contract for cause, then it shall …if <#employer> <terminates> #contract for cause, then <it> shall …

If the user would then choose the plural “Group Companies” as a concept label, the sentence would become “if the Group Companies terminate the contract for cause, then they shall …”. With a singular concept label “Acme Inc”, the sentence would instead be “if Acme Inc terminates the contract for cause, then it shall …”.

If multiple concepts are present in a single clause file, then you need to indicate which concept a particular word refers to. For example, “if #employee wants to return the documents of #employer, then he will … ” would become “if #employee <wants: employee> to return the documents of #employer, then <he: employee> will …”.

Don’t worry, you do not need to surround every verb, adjective and pronoun in angular brackets. This will in any case be limited to the words that refer to a concept, and even then you should always ask yourself if the word can actually change if a different concept label would be chosen.

For example, in English, combinations of auxiliaries (can, must, shall, will, …) and infinitives will never need to be adapted because they are the same in singular and plural. Similarly, in French, possessive pronouns do not need to be adapted — for example, in the sentence “si #employé endommage sa voiture”, the possessive “sa” does not need to change if the employee would turn out to be female.

Furthermore, you should also ask yourself whether in your organisation there will actually be users who will change the gender or singular/plural form of a concept label. If the clauses you write will always be used by the same employer, then there is no need to worry about conjugations related to the employer. In fact, if the styling will never change either, you may even opt to hard-code “Employer” instead of turning it into concept #employer.

Datafields

Instead of hard-coding variable information, as you would do in Microsoft Word, you should refer to datafields. At the moment a document is shown on the screen or saved, ClauseBase will replace these placeholders with the actual data.

For example:

Traditional approach in WordDynamic approach in ClauseBase
The contract shall terminate on 5th January 2018#Contract shall terminate on #contract^termination-date

If you are referring to numbers you can also insert calculations, surrounded by curly brackets { }, and constructed using addition (+), subtraction (-), multiplication (*) or division (/). For example, you could write { #deal^value * #deal^correction-factor } to express a calculation in which the value of a deal is multiplied by the deal’s correction factor.

If you start doing heavy math, then please take into account that ClauseBase will follow the traditional precedence rules, so that 5 + 4 * 3 is equal to 17, and not 27. In case of doubt, please use parentheses — e.g. (5 + 4) * 3 — to better express what you intend to achieve.

You can also calculate with dates and durations. For example, {#contract^commencement-date + 3 months} will result in the date that is three months after the commencement date. By the way, besides “months”, you can also use “days”, “months”, “quarters” or “years” for durations.

Conditional text

Conditional text is probably the most interesting feature of the grammar, so let’s look at that now.

This feature allows you to make certain words, or even entire sentences or sub-clauses, subject to a condition. For example, if you would write:

The courts of {#applicable-law^country= "BE": Brussels | #applicable-law^country= "NL": Amsterdam} will be competent to resolve disputes.

…then ClauseBase will check the current contents of the datafield country of concept applicable-law. If that content would be equal to BE (for Belgium), then the word Brussels will be inserted, while if that content would be equal to NL (for the Netherlands), then the word Amsterdam will be inserted.

Typically in ClauseBase grammar we prefer to use codes to refer to predefined values in datafields. There are several reasons for this, including making it easier to draft clauses in multiple languages, avoiding errors, etc. This article explains the issue more in depth.

If the content would be equal to something else — say, FR for France — then the part between { … } will simply be dropped, which would result in The courts of will be competent to resolve disputes. Of course, that would be an incomplete sentence, so let’s correct it:

The courts of {#applicable-law^country= "BE": Brussels | #applicable-law^country= "NL": Amsterdam | else: #customer's city of establishment } will be competent to resolve disputes.

This new version of the conditional text will always result in a correct sentence, since if the datafield country is not equal to either BE or NL, ClauseBase will show the text after else:. However, it may be the case that you really do not want the user of your clause to ever set the datafield country to something other than Belgium (BE) or the Netherlands (NL). The following version would then probably be a better idea:

The courts of {#applicable-law^country = "BE": Brussels | #applicable-law^country = "NL": Amsterdam | #applicable-law^country = " " : !! court is missing !! | else: !! incorrect country selected !! } will be competent to resolve disputes.

The parts in between double exclamation marks will result in error messages that are prominently displayed in purple in a document preview.

Structure of conditional text

Conditional text may look scary at first, but is actually quite simple to understand. Essentially, you start and end with a curly bracket ({ }), and insert one or more conditions + outputs after the colon (:), separated by the pipe-symbol (|) as necessary.

The conditions themselves — i.e., the part before the colon — can be as complex as you like. For example, ClauseBase happily accepts a condition that would only insert certain words relating to an extended guarantee when the applicable law is Belgium and the contract value is simultaneously higher than 5,000 EUR, except if the signatory would be the CEO, in which case the contract value should be 10,000 EUR. In practice, however, most conditions are significantly easier to understand.

Writing conditions

The general rule is that conditions should boil down to some kind of comparison that can turn out to be true or false.

A simple comparison has three parts: a left value, an operator and a right value. If the values you are comparing are numbers, then the typical operators you learned in primary school can be used: equal to (=), greater than (>), smaller than (<), greater than or equal to (>=), and smaller than or equal to (<=). If you want to express that something should not be equal to something else, then you should use !=.

Instead of comparing single values, you can also compare calculations. For example, you could write :

  • {#deal^monthly-value * 3.2 < #deal^threshold-value * #deal^bonus-factor: … } (i.e.: “if the monthly value of the deal times 3.2 is smaller than the deal threshold value times the deal bonus factor, then …”); or
  • { #contract^commencement-date + 3 months < 2018_01_01: … } (i.e.: if three months past the contract commencement date is still earlier than 1 January 2018, then ….”)

If you are comparing text values, then you should surround them with either single quotes or double quotes.

Multiple comparisons can be combined with AND / OR. For example, #applicable-law^country= "Belgium" AND #contract^value > 5000 EUR expresses the requirement that not only the applicable law must be identical to “Belgium”, but also that at the same time a contract’s value must be higher than 5,000 EUR. If, instead, it would be sufficient that either the applicable law is Belgium or the contract value is higher than 5,000 EUR, then you would write OR instead: #applicable-law^country= "Belgium" OR #contract^value > 5000 EUR.

Bold, italics and underlined text

As previously explained, ClauseBase emphasizes reusability, and therefore tries to avoid situations where styling information (font name, spacing, etc.) would end up in the clauses themselves. Instead, ClauseBase will add such styling afterwards, at the moment the document is shown on screen, or put into a .DOCX-file or PDF-file.

This separation between content and layout may seem like extra work compared to MS Word (which always combines content and layout). However, from a document automation perspective this has the huge advantage that you can change the layout without having to change the content — so two documents produced for two different clients can have the same legal content, but can look completely different.

Occasionally you will, however, have a valid need to deviate from this principle, e.g. because you really want certain words to be formatted in bold, irrespective of the styling that will ultimately be chosen by the user. By way of exception, ClauseBase does allow you to do so, by surrounding those words with a tilde (~). For example:

1. ~These words~ will be shown in ~bold~.

will be formatted as:

1. These words will be shown in bold.

Additionally, you can do the same for text in italics by using the backtick (`). So:

1. `These words` will be shown in `italics`.

will be formatted as:

1. These words will be shown in italics.

Finally, you can also format text to be underlined so that:

1. \These words\ will be \underlined\.

will be formatted as:

1. These words will be underlined.