Skip to main content

Writing Schemas with AI

warning

RehabAlpha is still under active development. It is not yet HIPAA compliant and should only be used with dummy data.

AI tools such as ChatGPT, Gemini, and Claude can be very effective for drafting RehabAlpha schemas.

In many cases, using AI is the fastest way to go from a vague idea like:

  • “I need a PT evaluation template”
  • “I want a falls section”
  • “I need a Medicare-focused SNF template”

to a usable first draft.

That said, AI works best when you treat it like a fast draft assistant, not a source of perfect truth.

The better your prompt, the better your schema draft will be.

What AI is good at​

AI can help you:

  • generate a first-pass schema from a clinical description
  • turn a plain-English workflow into structured nodes
  • suggest reusable option lists
  • add conditionals
  • refactor repeated sections
  • explain validation errors
  • convert inline options into options nodes
  • improve naming consistency

AI is especially useful when you already know the form you want, but do not want to hand-write every node yourself.

What AI is not good at​

AI can still make mistakes.

For example, it may:

  • invent node properties that RehabAlpha does not support
  • reference document types or node types incorrectly
  • create broken IDs or broken references
  • overcomplicate conditional logic
  • produce schemas that are technically valid but hard to maintain
  • ignore your organization's actual clinical workflow

Because of that, you should always review AI-generated schemas before using them.

A good workflow​

A practical workflow looks like this:

  1. describe the form you want in plain English
  2. give the AI the RehabAlpha schema docs
  3. ask for a small, focused schema first
  4. test the result in RehabAlpha
  5. refine the schema in short iterations

Start small.

It is usually better to ask for:

  • one template
  • one section
  • one conditional branch
  • one reusable option list

than to ask for a giant enterprise-wide schema in a single prompt.

Start with context​

AI performs much better when it understands:

  • what kind of therapy company you are describing
  • what document type you are targeting
  • what discipline the template is for
  • what sections the clinician needs
  • what fields should be required
  • what should appear conditionally
  • whether you prefer reusable options
  • whether you want structured option values

The more concrete your instructions, the better the result.

Example prompt​

Here is a simple starting prompt:

Review the documentation for RehabAlpha Schemas at the following URLs:

1. https://www.rehabalpha.com/docs/guides/schemas/
2. https://www.rehabalpha.com/docs/guides/schemas/examples
3. https://www.rehabalpha.com/docs/guides/schemas/writing-your-own-schema

Now produce a simple schema for an outpatient therapy company. Include a section for right knee range of motion and left knee range of motion.

That prompt is good because it:

  • gives the AI documentation context
  • tells it what to build
  • keeps the scope small
  • names two concrete clinical requirements

A stronger prompt​

You will usually get better results by being more specific.

For example:

Review the documentation for RehabAlpha Schemas at the following URLs:

1. https://www.rehabalpha.com/docs/guides/schemas/
2. https://www.rehabalpha.com/docs/guides/schemas/examples
3. https://www.rehabalpha.com/docs/guides/schemas/writing-your-own-schema

Now create a RehabAlpha schema for an outpatient physical therapy company.

Requirements:
- Create one template for evaluations
- Name the template "Outpatient PT Evaluation"
- Include groups for Subjective, Knee Range of Motion, Assessment, and Plan
- Include separate number inputs for right knee flexion, right knee extension, left knee flexion, and left knee extension
- Use clear, predictable node IDs
- Use only supported RehabAlpha node types and properties
- Return only the schema code in JSON5 format

This version is stronger because it tells the AI:

  • the discipline
  • the document type
  • the section structure
  • the exact fields
  • the formatting expectation
  • the constraint to use only supported schema features

Good prompt patterns​

Here are some instructions that often improve results.

Ask for a small scope​

Better:

  • “Create one evaluation template”
  • “Create one falls section”
  • “Create one pain assessment group”

Worse:

  • “Create every template our company might ever need”

Ask for supported node types only​

This helps prevent hallucinated properties or unsupported features.

Example:

Use only supported RehabAlpha node types and properties from the documentation.

Ask for predictable IDs​

Example:

Use clear IDs like pt_eval_template, pain_group, pain_level_input, and side_options.

Ask for reusable options where appropriate​

Example:

If the same options are reused, define them as options nodes instead of repeating inline arrays.

Ask for structured values when consistency matters​

Example:

Use { label, value } option objects when the stored values should remain stable for reporting.

Ask for code only when you want copy-paste output​

Example:

Return only the schema code in JSON5 format with no explanation.

Ask for explanation when you want to learn​

Example:

After the schema, explain why you used each group, conditional, and options.

Useful follow-up prompts​

AI is often most useful on the second or third turn.

Here are some strong follow-up prompts you can use.

Refine structure​

Refactor this schema to use more reusable options nodes and more consistent node IDs.

Add conditional logic​

Revise this schema so that pain detail fields only appear when the user indicates pain is present.

Simplify complexity​

This schema is valid but too complicated. Simplify the conditional logic and make it easier to maintain.

Fix validation issues​

This schema fails validation in RehabAlpha. Find likely problems such as broken references, duplicate IDs, invalid template placement, or unsupported properties, then produce a corrected version.

Add discipline or setting awareness​

Revise this schema so that a mobility section only appears when *disciplineId is PT and *facilityType is SNF.

Convert repeated inline options​

Find repeated inline options arrays in this schema and refactor them into reusable options nodes.

Improve naming​

Rename the node IDs in this schema so they follow a consistent pattern using suffixes like _template, _group, _logic, _input, and _options.

Ask AI to review, not just generate​

You do not have to use AI only for initial drafts.

AI can also help review an existing schema.

For example, you can ask it to:

  • identify broken references
  • find duplicate or inconsistent naming
  • locate sections that should probably become reusable
  • detect overcomplicated conditional logic
  • suggest better group labels
  • propose a cleaner template default strategy

Example prompt:

Review this RehabAlpha schema for maintainability. Focus on:
- naming consistency
- repeated option lists
- overcomplicated conditionals
- unclear labels
- opportunities to split giant templates into smaller ones

Then provide a revised version.

Give AI your actual goals​

Do not just ask for “a schema.”

Tell the AI what the clinician is trying to accomplish.

For example, this is weak:

Create a PT schema.

This is much stronger:

Create a RehabAlpha evaluation schema for outpatient physical therapy. The clinician needs to document chief complaint, history, pain, knee range of motion, gait, assessment, and plan. Keep it clean and beginner-friendly.

Clinical intent usually produces better results than vague technical requests.

Include constraints that matter to you​

You can improve the output by specifying your preferences.

Examples:

  • “Keep the schema beginner-friendly.”
  • “Avoid deeply nested conditionals.”
  • “Prefer reusable options nodes.”
  • “Prefer structured option values.”
  • “Keep the template focused and not overly long.”
  • “Do not use inline child objects unless necessary.”
  • “Use comments sparingly.”
  • “Optimize for readability over cleverness.”

This helps the AI match your style.

A practical example​

Here is a more realistic prompt for iterative authoring:

Review the RehabAlpha schema documentation and create a JSON5 schema for an outpatient physical therapy evaluation.

Requirements:
- One evaluation template
- Clear IDs with consistent naming
- Groups for Subjective, Knee ROM, Functional Mobility, Assessment, and Plan
- Knee ROM should include right and left flexion and extension as number inputs
- Include a yes/no pain question
- If pain is present, show pain location and pain level
- Reuse option lists where appropriate
- Keep the logic easy to understand
- Use only supported RehabAlpha node types and properties

After the schema, briefly explain any reusable options or conditionals you used.

This prompt usually produces a much stronger draft than a one-sentence request.

Review checklist for AI-generated schemas​

Before copying an AI-generated schema into RehabAlpha, review it for these common issues:

  • Does every node have a unique ID?
  • Are all references valid?
  • Are templates root nodes?
  • Are option references pointing to options nodes?
  • Are the IDs readable and predictable?
  • Are conditionals understandable?
  • Are reusable lists actually reused?
  • Are the labels clinician-friendly?
  • Is the schema focused, or is it trying to do too much?
  • Does it use only supported node types and properties?

Even a strong AI result usually benefits from one manual cleanup pass.

Common mistakes AI makes​

Watch for these specifically:

Invented properties​

AI may add properties that sound reasonable but are not supported by RehabAlpha.

Wrong operator choice​

AI may confuse:

  • isIn vs includes
  • isNotIn vs doesNotInclude

Broken references​

AI may reference nodes that were renamed or never defined.

Inconsistent IDs​

AI may mix naming styles, such as:

  • painInput
  • pain_level
  • PainLevelInput

Overengineered conditionals​

AI sometimes creates conditionals that technically work but are much harder to understand than necessary.

Repeated option arrays​

AI often duplicates inline arrays instead of extracting shared options into options nodes.

Treat AI drafts like junior-dev drafts​

A useful mindset is to treat AI output the same way you would treat a quick draft from a capable junior developer:

  • often helpful
  • often fast
  • sometimes impressive
  • never above review

That mindset keeps expectations realistic and usually leads to better final schemas.

Best practices summary​

When using AI for RehabAlpha schemas:

  • give the AI the documentation
  • describe the clinical workflow clearly
  • start with a small scope
  • ask for supported node types only
  • prefer iterative refinement over giant one-shot prompts
  • review the output carefully before using it

AI is excellent at helping you move faster.

You will still get the best results when you combine AI speed with human judgment.

Try it​

Copy one of the example prompts above into your preferred AI tool and see what it produces.

Then refine the result with a follow-up prompt such as:

Now simplify this schema, make the IDs more consistent, and convert repeated inline options into reusable options nodes.

That kind of short iterative loop is often the fastest path to a strong schema.

Where to go next​

After this page, the most helpful follow-up articles are:

  • Schemas Overview
  • Writing Your Own Schema
  • Tips & Tricks
  • Frequently Asked Questions
  • Test Your Knowledge
  • Schema Library