Skip to main content
The toolsArgs 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.

​
Required structure

The schema must obligatorily 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

​
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"
        }
      }
    }
  }
}

​
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 CIE10 and being as specific as possible with the provided information."
        },
        "name": {
          "type": "string",
          "description": "Diagnosis name using the CIE10."
        },
        "description": {
          "type": "string",
          "description": "Justification or description of the diagnosis using the CIE10."
        }
      }
    },
    "source": "cie_latam",
    "description": "List the diagnosis/diagnoses determined during this medical consultation, including name, description (justification), and CIE10 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

​
Enabling/Disabling User Customization

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

​
Validation and testing

Before deploying a schema in production:
  1. Validate JSON syntax using linting tools
  2. Test with real data to verify correct generation
  3. Review with medical professionals the clinical relevance of fields
  4. Verify references to standard medical terminologies