Notations - Flows & Alignments

As we refine our spec for Neon Notations, we’re setting some foundational rules to keep everything structured and easy to use. These rules will evolve over time, but here are some key principles we’re following.

In our system, notations are stored as questionnaires in the database. If you’re looking for related tests, you’ll find them in:

📂 ./test/neon_law/curiosity/questionnaire_test.exs

Flows & Alignments

What are Flows & Alignments?

They are special dictionaries that determine how a user or staff member interacts with a questionnaire. Flows are for the end user and alignments are for Neon Law staff, which is always supervised by a lawyer.

Here are the key rules:

1️⃣ Keep It Two Layers Deep

A flow or alignment should always be structured as a dictionary with only two levels of keys and values.

🚫 Incorrect: (Too many layers!)

%{
  :BEGIN => %{_: %{_: "END"}}
}

✅ Correct: (Just two levels deep!)

%{
  :BEGIN => %{_: "END"}
}

2️⃣ Valid Top-Level Keys Only

The top-level keys must follow one of these rules:

• Either :BEGIN
• Or a valid question code

For example, let’s say we have a question stored in our database with the code what_is_your_name.

🚫 Incorrect: (Invalid key: do_you_want_potato_salad is not a question code)

%{
  :BEGIN => %{_: "what_is_your_name"},
  "do_you_want_potato_salad": %{_: "END"}
}

✅ Correct: (Valid key: what_is_your_name is a question code)

%{
  :BEGIN => %{_: "what_is_your_name"},
  "what_is_your_name": %{_: "END"}
}

3️⃣ Use Labels Correctly in Questionnaires

Questionnaires often use labels to reference questions. These labels are used in the document_text field to help structure responses.

🚫 Incorrect: (Label mismatch!)

%{
  :BEGIN => %{_: "what_is_your_name__personal_name"},
  "what_is_your_name__dog_name": %{_: "END"}
}

✅ Correct: (Matching labels for consistency!)

%{
  :BEGIN => %{_: "what_is_your_name__personal_name"},
  "what_is_your_name__personal_name": %{_: "END"}
}

📌 Why does this matter?

In this example, the document_text can now correctly reference personal_name when storing the user’s answer to the what_is_your_name question.

More Rules Coming Soon! 🚀

We’re actively refining Neon Notations, so expect more rules and best practices in the future. If you have feedback or ideas, we’d love to hear them! Please email us at notations@neonlaw.com.