Clinical data schemas

The template property defines the structure of clinical data that SofIA should generate. It must be a complete JSON Schema Draft-07 schema that specifies the fields, types, and validations required for medical documentation.

The template prop accepts a JSON Schema defining the report structure. Throughout this page, “template” refers to the prop and “schema” refers to the JSON Schema content.

Note: This property was previously called toolsArgs/toolsargs. The legacy name is still supported but deprecated and will be removed in v2.0. Use template instead.

If your integration sends a configuration payload (using template or legacy toolsargs), you can add an accessibility variable at the same level to define visual preferences. Use the property names exactly as shown below (language-agnostic payload keys). For consistency, each option value is an array of accepted labels/aliases.

{
  "template": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "general_consultation_v1",
    "type": "object",
    "properties": {
      "diagnosis": { "type": "string" }
    }
  },
  "templateid": "general-consultation-v1",
  "accessibility": {
    "text_size": ["Text size", "Font size", "Large text"],
    "color_contrast": ["Color adjustment", "Color contrast", "High contrast mode"],
    "color_inversion": ["Color inversion"],
    "color_filters": ["Color filters", "Color blindness"],
    "bold_text": ["Bold text"],
    "reduce_transparency": ["Reduce transparency"],
    "grayscale": ["Grayscale"]
  }
}

Recommended technical term: Accessibility (a11y). The number 11 represents the letters between a and y.

Color and contrast options are often grouped under Visual accommodations or Display preferences.

How Templates Work

Input

The JSON Schema template and conversation context are provided to the SofIA SDK.

AI Processing

The SDK sends the data via LangGraph Streaming for AI processing.

Structured Output

The AI generates a structured report matching the schema, delivered to the EHR/HIS via the handle-report callback.

The template defines what data to extract. SofIA’s AI reads the conversation context and fills the schema fields automatically, delivering a structured JSON report that matches your schema.

Required structure

The schema must include:

$schema: Reference to the JSON Schema Draft-07 standard
title: Identifier of the clinical document type
type: Must be “object” for structured documents
required: Array with mandatory fields
properties: Detailed definition of each field

The template prop alone does not enable report generation — you must also set templateid. Without both props, SofIA operates in chat-only mode: audio transcription and clinical chat remain fully functional, but the generate button is hidden because there is no schema to send to the AI agents for structured data extraction.

Basic example

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "create_clinical_notes/v1",
  "type": "object",
  "required": ["primary_diagnosis"],
  "properties": {
    "primary_diagnosis": {
      "type": "string",
      "description": "Patient's primary diagnosis",
      "source": "ICD10"
    },
    "symptoms": {
      "type": "array",
      "description": "List of observed symptoms",
      "items": {
        "type": "string"
      }
    },
    "physical_examination": {
      "type": "object",
      "properties": {
        "blood_pressure": {
          "type": "object",
          "properties": {
            "systolic": {"type": "number", "minimum": 50, "maximum": 250},
            "diastolic": {"type": "number", "minimum": 30, "maximum": 150}
          }
        },
        "heart_rate": {
          "type": "number",
          "description": "Heart rate in beats per minute"
        }
      }
    }
  }
}

Passing templates to the component

As an HTML attribute — wrap the JSON in single quotes, use double quotes inside:

<sofia-sdk
  template='{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"diagnosis":{"type":"string"}}}'
></sofia-sdk>

Programmatically (recommended for complex schemas) — set via JavaScript:

const sofia = document.querySelector('sofia-sdk');
sofia.template = mySchemaObject;
// Or as string:
sofia.setAttribute('template', JSON.stringify(mySchemaObject));

Clinical coding sources

Use the source property on a field to enable normalization with standard medical terminologies. The following values are supported:

Value	System	Description
`"ICD10"`	ICD-10 (International)	International Classification of Diseases, 10th revision
`"cie_latam"`	CIE-10 (Latin America)	Latin American adaptation of ICD-10

Contact support@omniloy.com for additional coding system support (e.g., SNOMED CT, LOINC).

Specialized fields

Medical terminology sources

Use the source property to enable normalization with standard terminologies:

{
  "diagnosis": {
    "name": "diagnosis",
    "type": "array",
    "items": {
      "type": "object",
      "required": [
        "code",
        "name"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "Diagnosis code using the ICD-10 and being as specific as possible with the provided information."
        },
        "name": {
          "type": "string",
          "description": "Diagnosis name using the ICD-10."
        },
        "description": {
          "type": "string",
          "description": "Justification or description of the diagnosis using the ICD-10."
        }
      }
    },
    "source": "cie_latam",
    "description": "List the diagnosis/diagnoses determined during this medical consultation, including name, description (justification), and ICD-10 code if applicable. If no diagnosis is explicitly stated, suggest the most likely possibilities based on the conversation."
  }
}

Structured vital signs

{
  "vital_signs": {
    "type": "array",
    "description": "Patient's vital signs",
    "items": {
      "type": "object",
      "required": ["parameter", "value"],
      "properties": {
        "parameter": {
          "type": "string",
          "enum": ["Systolic Blood Pressure", "Diastolic Blood Pressure", "Heart Rate", "Temperature", "O2 Saturation"]
        },
        "value": {"type": "number"},
        "unit": {"type": "string"},
        "measurement_date": {"type": "string", "format": "date-time"}
      }
    }
  }
}

Supported data types

Basic types

string: Free or controlled text
number: Numeric values (integers or decimals)
boolean: True/false values
array: Lists of elements
object: Complex nested structures

Advanced validations

{
  "age": {
    "type": "number",
    "minimum": 0,
    "maximum": 150,
    "description": "Patient age in years"
  },
  "email": {
    "type": "string",
    "format": "email",
    "description": "Contact email address"
  },
  "birth_date": {
    "type": "string",
    "format": "date",
    "description": "Birth date (YYYY-MM-DD)"
  },
  "gender": {
    "type": "string",
    "enum": ["Male", "Female", "Other", "Not specified"],
    "description": "Patient gender"
  }
}

Technical limitations

Maximum size: 100 KB per schema
Depth: Maximum 10 nesting levels
Complexity: Avoid overly complex schemas that may affect performance

Best practices

Detailed descriptions

Provide clear and specific descriptions for each field:

{
  "description": "Primary diagnosis according to established clinical criteria, using ICD-10 terminology when possible"
}

Appropriate validations

Implement validations that reflect clinical reality:

{
  "weight": {
    "type": "number",
    "minimum": 0.5,
    "maximum": 500,
    "description": "Patient weight in kilograms"
  }
}

Flexible structures

Design schemas that allow for clinical variability:

{
  "medications": {
    "type": "array",
    "items": {
      "type": "object",
      "required": ["name"],
      "properties": {
        "name": {"type": "string"},
        "dose": {"type": "string"},
        "frequency": {"type": "string"},
        "administration_route": {"type": "string"}
      }
    }
  }
}

Property Customization

The `isConfigurable` property

Default value: true (all fields are configurable by default) When isConfigurable is true (default), the healthcare professional can edit the generated field value in the SofIA interface before finalizing the report. Set to false for fields that should be generated but not editable. Configurable field (default behavior):

{
  "treatment_plan": {
    "isConfigurable": true,
    "type": "string",
    "description": "Recommended treatment plan"
  }
}

Non-configurable field:

{
  "diagnosis": {
    "isConfigurable": false,
    "name": "diagnosis",
    "type": "array",
    "items": {
      "type": "object",
      "required": [
        "code",
        "name"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "Diagnosis code using the ICD-10 and being as specific as possible with the provided information."
        },
        "name": {
          "type": "string",
          "description": "Diagnosis name using the ICD-10."
        },
        "description": {
          "type": "string",
          "description": "Justification or description of the diagnosis using the ICD-10."
        }
      }
    },
    "description": "List the diagnosis/diagnoses determined during this medical consultation, including name, description (justification), and ICD-10 code if applicable. If no diagnosis is explicitly stated, suggest the most likely possibilities based on the conversation."
  }
}

Debugging your template

Enable debug mode

Add debug="true" to the SofIA component to enable detailed console logging. All SDK logs are prefixed with [Sofia SDK], making them easy to filter in browser DevTools.

<sofia-sdk
  debug="true"
  baseurl="https://api.example.com/v1"
  wssurl="wss://ws.example.com"
  apikey="sk-your-api-key-here"
  userid="user_12345"
  patientid="patient_67890"
  templateid="your-template-id"
  template='{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Clinical Notes",
    "type": "object",
    "properties": {
      "diagnosis": {"type": "string", "description": "Primary diagnosis"}
    },
    "required": ["diagnosis"]
  }'
></sofia-sdk>

In your browser DevTools Console, use the filter [Sofia SDK] to isolate SDK logs from other application output.

Template validation checklist

Before debugging in the browser, verify these five points:

Valid JSON Schema — includes "$schema": "http://json-schema.org/draft-07/schema#" header
Both template and templateid are present — the generate button only appears when both are provided
properties defined with at least 1 field — an empty properties object results in chat-only mode
Schema size under 100KB — larger schemas are rejected
required fields match existing properties — any mismatch causes validation errors

Console log reference

When debug="true" is enabled, these are the key messages related to templates and report generation:

Console message	Meaning	Action
`[Sofia SDK] Settings - Template loaded: {n} fields`	Template was parsed successfully with `n` fields	None — this is the expected success message
`[Sofia SDK] Settings - Template validation failed`	Template JSON is malformed or missing required schema keys	Check JSON syntax and ensure `$schema`, `type`, and `properties` are present
`[Sofia SDK] Settings - Using fallback template`	Local template was invalid; SDK fell back to server-side template	Fix the local `template` prop — check for syntax errors or invalid field types
`[Sofia SDK] API - Report generation started`	User clicked Generate; processing has begun	None — wait for completion or failure
`[Sofia SDK] API - Report generation completed`	Report was generated and delivered to `handleReport`	Verify the data in your `handleReport` callback
`[Sofia SDK] API - Report generation failed: {error}`	Report generation encountered an error	Check the error message for details (`configError`, `authError`, `apiError`, or `settingsError`)

Common issues

Generate button doesn't appear

Symptom: The SofIA component loads in chat-only mode — no generate button is visible.Cause: The generate button requires both template and templateid to be present and valid. If either is missing or if the template has zero parseable fields, hasTemplateConfig evaluates to false and the button is hidden.Solution:

Verify both template and templateid attributes are set on the component
Enable debug="true" and look for Template loaded: {n} fields — if n is 0 or the message doesn’t appear, the template is invalid
Validate that template contains at least one property inside properties

handleReport returns an empty object

Symptom: The handleReport callback fires but the report object is {} or contains only empty values.Cause: The template fields don’t match the conversation context. SofIA extracts data based on what was discussed — if the conversation doesn’t contain information relevant to your template fields, those fields will be empty.Solution:

Ensure the conversation covers topics related to your template fields before clicking Generate
Check that field description values are clear and specific — vague descriptions lead to poor extraction
Enable debug="true" and verify Report generation completed appears (not failed)

handleReport returns partial data

Symptom: Some fields in the report are populated but others are missing or null.Cause: The AI could only extract data for fields that were discussed in the conversation. Fields marked as required in your schema are prioritized, but optional fields may be omitted if the conversation doesn’t contain relevant information.Solution:

Review which fields are missing — do they correspond to topics discussed in the conversation?
Add more specific description values to help the AI identify relevant information
Consider marking critical fields as required in your schema

Template falls back to server defaults

Symptom: The generated report uses a different structure than your local template. In debug mode, you see Using fallback template.Cause: The SDK couldn’t parse your local template prop. It attempts three parsing strategies (JSON.parse, prefix removal, Function eval) — if all fail, it falls back to the server-configured template for your templateid.Solution:

Validate your template JSON at jsonlint.com
Ensure the template is passed as a valid JSON string, not a JavaScript object
Check for special characters or encoding issues in the template string
In debug mode, look for Template validation failed for specific error details

Verifying handleReport output

Use the following pattern to inspect the report data in your browser console:

function handleReport(report) {
  // Log the full report for debugging
  console.log('[My App] Report received:', JSON.stringify(report, null, 2));

  // Compare report keys with expected template fields
  const expectedFields = ['primary_diagnosis', 'symptoms', 'physical_examination'];
  const receivedFields = Object.keys(report);
  const missingFields = expectedFields.filter(f => !receivedFields.includes(f));

  if (missingFields.length > 0) {
    console.warn('[My App] Missing fields:', missingFields);
  }

  // Process the report in your application
  // ...
}

Use JSON.stringify(report, null, 2) for a formatted view of the report object. This makes it easier to spot missing or unexpected values compared to the default console.log output.

For more debugging tools and how to read SDK logs, see Troubleshooting — Debugging and Logging.

Installation and Configuration

Framework Integration

Features

Support

How Templates Work

Required structure

Basic example

Passing templates to the component

Clinical coding sources

Specialized fields

Medical terminology sources

Structured vital signs

Supported data types

Basic types

Advanced validations

Technical limitations

Best practices

Detailed descriptions

Appropriate validations

Flexible structures

Property Customization

The `isConfigurable` property

Debugging your template

Enable debug mode

Template validation checklist

Console log reference

Common issues

Verifying handleReport output

Installation and Configuration

Framework Integration

Features

Support

​Accessibility (a11y)

​How Templates Work

​Required structure

​Basic example

​Passing templates to the component

​Clinical coding sources

​Specialized fields

​Medical terminology sources

​Structured vital signs

​Supported data types

​Basic types

​Advanced validations

​Technical limitations

​Best practices

​Detailed descriptions

​Appropriate validations

​Flexible structures

​Property Customization

​The isConfigurable property

​Debugging your template

​Enable debug mode

​Template validation checklist

​Console log reference

​Common issues

​Verifying handleReport output

Accessibility (a11y)

How Templates Work

Required structure

Basic example

Passing templates to the component

Clinical coding sources

Specialized fields

Medical terminology sources

Structured vital signs

Supported data types

Basic types

Advanced validations

Technical limitations

Best practices

Detailed descriptions

Appropriate validations

Flexible structures

Property Customization

The `isConfigurable` property

Debugging your template

Enable debug mode

Template validation checklist

Console log reference

Common issues

Verifying handleReport output