Adding Additional Metadata via API
Your API supports extensive metadata through multiple flexible fields. Here's how to add custom metadata at different levels:
🏷️ Metadata Fields Available
1. Individual Feedback Metadata
A. Built-in Structured Fields
{
"title": "Assignment Feedback",
"feedback_content": "<h3>Great work!</h3>...",
"teacher_name": "Dr. Smith",
"teacher_experience_level": "experienced",
"assessment_type": "essay",
"student_level": "Undergraduate Year 2",
"subject_area": "Mathematics",
"student_context": "Student received B+ grade, First attempt",
// ✅ Structured metadata fields
"criteria_addressed": [
"problem_solving",
"communication",
"mathematical_reasoning",
"presentation"
]
}
B. Flexible JSON Metadata
{
"title": "Assignment Feedback",
"feedback_content": "<h3>Great work!</h3>...",
// ... standard fields ...
// ✅ Custom extraction metadata (any JSON structure)
"extraction_metadata": {
"source_document": "assignment_rubric_v2.pdf",
"extraction_method": "manual_entry",
"document_version": "2.1",
"extracted_by": "teaching_assistant_id_123",
"extraction_date": "2024-01-20T15:30:00Z",
"quality_score": 0.95,
"language_detected": "en",
"original_format": "docx",
"file_size_bytes": 1024000,
"custom_tags": ["urgent", "final_submission", "requires_followup"],
"institutional_data": {
"course_code": "MATH101",
"semester": "Spring 2024",
"assignment_number": 3,
"due_date": "2024-01-25",
"late_submission": false,
"student_id": "S123456",
"section": "A"
},
"feedback_context": {
"is_revision": false,
"previous_grade": null,
"submission_attempt": 1,
"time_spent_minutes": 45,
"word_limit": 1500,
"citation_style": "APA"
},
"ai_processing": {
"model_version": "v2.1",
"confidence_score": 0.87,
"processing_time_ms": 2340,
"flags": ["grammar_check_needed"]
}
}
}
2. Batch-Level Metadata
When creating batch evaluations, you can add extensive metadata:
{
"name": "Weekly Feedback Review - Jan 2024",
"description": "Evaluation of math assignment feedback quality",
"rubric_id": 1,
"organization_id": 1,
"feedback_ids": [101, 102, 103],
"evaluation_focus": "Focus on constructive feedback quality",
"international_standards": ["APA", "Cambridge Assessment"],
// ✅ Flexible batch metadata
"metadata": {
"batch_type": "weekly_review",
"academic_period": {
"semester": "Spring 2024",
"week": 3,
"course_codes": ["MATH101", "MATH102"],
"instructor_cohort": "junior_faculty"
},
"evaluation_settings": {
"focus_areas": [
"constructive_criticism",
"specific_examples",
"encouragement_balance",
"grammar_quality"
],
"weight_distribution": {
"content_quality": 0.4,
"constructiveness": 0.3,
"clarity": 0.2,
"encouragement": 0.1
},
"comparison_baseline": "department_average_2023"
},
"institutional_context": {
"department": "Mathematics",
"faculty_development_program": "Teaching Excellence Initiative",
"evaluation_cycle": "mid_semester",
"stakeholders": ["department_head", "teaching_coordinator"],
"follow_up_required": true
},
"reporting_preferences": {
"anonymize_teacher_names": false,
"include_individual_scores": true,
"generate_summary_stats": true,
"export_formats": ["pdf", "csv", "xlsx"],
"distribution_list": ["coordinator@university.edu"]
},
"custom_fields": {
"project_code": "TQI-2024-Q1",
"budget_code": "ACAD-EVAL-001",
"external_evaluation": false,
"pilot_program": true
}
}
}
🚀 Practical Examples
Example 1: Course Management System Integration
{
"organization_id": 1,
"feedbacks": [
{
"title": "Calculus Midterm Feedback",
"feedback_content": "<h3>Midterm Performance Review</h3>...",
"teacher_name": "Prof. Wilson",
"teacher_experience_level": "expert",
"assessment_type": "essay",
"student_level": "Undergraduate Year 1",
"subject_area": "Mathematics",
"criteria_addressed": [
"problem_solving",
"mathematical_communication",
"procedural_fluency",
"conceptual_understanding"
],
"extraction_metadata": {
// LMS Integration
"lms_data": {
"course_id": "CALC_101_SP24",
"assignment_id": "midterm_exam_1",
"student_lms_id": "student_12345",
"submission_timestamp": "2024-01-20T14:30:00Z",
"late_penalty_applied": false,
"attempts_allowed": 1,
"time_limit_minutes": 120
},
// Grading Context
"grading_session": {
"grader_id": "prof_wilson_001",
"grading_date": "2024-01-22T16:45:00Z",
"grading_duration_minutes": 25,
"grading_location": "office",
"mood_indicator": "focused",
"distractions": "none"
},
// Student Context
"student_profile": {
"academic_standing": "good",
"previous_course_grade": "B+",
"attendance_rate": 0.95,
"participation_score": 8.5,
"help_sessions_attended": 3,
"learning_accommodations": ["extended_time"]
},
// Content Analysis
"content_analysis": {
"question_types_attempted": ["computation", "proof", "application"],
"difficulty_levels": [3, 4, 5],
"topics_covered": ["derivatives", "chain_rule", "optimization"],
"common_errors": ["sign_mistakes", "algebraic_manipulation"],
"strength_areas": ["setup", "conceptual_understanding"]
}
}
}
]
}
Example 2: Quality Assurance Program
{
"organization_id": 1,
"feedbacks": [
{
"title": "Writing Portfolio Review",
"feedback_content": "<h2>Portfolio Assessment</h2>...",
"teacher_name": "Dr. Martinez",
"teacher_experience_level": "experienced",
"assessment_type": "portfolio",
"student_level": "Graduate",
"subject_area": "English Composition",
"criteria_addressed": [
"thesis_development",
"argument_structure",
"evidence_integration",
"writing_mechanics",
"critical_thinking"
],
"extraction_metadata": {
// Quality Assurance
"qa_tracking": {
"review_cycle": "Q1_2024",
"qa_reviewer": "senior_faculty_committee",
"calibration_session": "2024-01-15",
"inter_rater_reliability": 0.89,
"blind_review": true,
"second_reader_required": false
},
// Faculty Development
"professional_development": {
"teacher_cohort": "writing_intensive_fellows",
"training_completed": ["rubric_design", "constructive_feedback"],
"mentorship_program": "senior_faculty_mentor",
"feedback_certification": "level_2",
"last_training_date": "2023-08-15"
},
// Assessment Innovation
"innovation_tracking": {
"new_techniques_used": ["peer_feedback_integration", "voice_comments"],
"technology_tools": ["audio_feedback", "collaborative_annotation"],
"experimental_approaches": true,
"research_participation": "feedback_effectiveness_study",
"data_collection_consent": true
},
// Institutional Research
"research_data": {
"anonymized_for_research": true,
"study_participants": ["teacher", "student"],
"longitudinal_tracking": true,
"outcome_measures": ["engagement", "improvement", "satisfaction"],
"ethics_approval": "IRB-2024-001"
}
}
}
]
}
Example 3: Multi-Language/International Context
{
"organization_id": 1,
"feedbacks": [
{
"title": "Filosofía Práctica - Ensayo Final",
"feedback_content": "<h3>Evaluación del Ensayo</h3><p>El estudiante demuestra...</p>",
"teacher_name": "Prof. García",
"teacher_experience_level": "master",
"assessment_type": "essay",
"student_level": "Licenciatura - Año 3",
"subject_area": "Filosofía",
"criteria_addressed": [
"argumentación_lógica",
"uso_de_fuentes",
"claridad_expresiva",
"pensamiento_crítico"
],
"extraction_metadata": {
// Internationalization
"language_context": {
"feedback_language": "es",
"student_native_language": "es",
"institutional_language": "es",
"translation_needed": false,
"cultural_context": "latin_american",
"regional_standards": "mexican_education_system"
},
// Academic System
"academic_system": {
"grading_scale": "0-10_mexican",
"credit_system": "SATCA",
"academic_calendar": "semester",
"degree_level": "licenciatura",
"specialization": "filosofia_practica",
"thesis_track": true
},
// Institutional Context
"institutional_data": {
"university_type": "public",
"accreditation": "COPAES",
"international_agreements": ["student_exchange_EU", "research_collaboration"],
"quality_frameworks": ["ISO_21001", "CIEES"],
"ranking_participation": true
},
// Cultural Adaptation
"cultural_metadata": {
"feedback_style": "formal_respectful",
"directness_level": "moderate",
"encouragement_emphasis": "high",
"family_involvement": "considered",
"social_context": "first_generation_college"
}
}
}
]
}
🔧 API Implementation
Enhanced API Endpoint
# Your existing API already supports these fields!
# Just include them in your JSON payload:
@csrf_exempt
@require_api_auth
def api_bulk_feedback_submission(request):
"""Enhanced to show metadata support"""
try:
data = json.loads(request.body)
organization_id = data.get('organization_id')
feedbacks_data = data.get('feedbacks', [])
created_feedbacks = []
with transaction.atomic():
for feedback_data in feedbacks_data:
# All these fields are supported:
feedback = StandaloneFeedback.objects.create(
title=feedback_data['title'],
feedback_content=feedback_data['feedback_content'],
teacher_name=feedback_data.get('teacher_name', ''),
teacher_experience_level=feedback_data.get('teacher_experience_level'),
assessment_type=feedback_data['assessment_type'],
student_level=feedback_data.get('student_level', ''),
subject_area=feedback_data.get('subject_area', ''),
# ✅ Structured metadata
criteria_addressed=feedback_data.get('criteria_addressed', []),
# ✅ Flexible JSON metadata
extraction_metadata=feedback_data.get('extraction_metadata', {}),
uploaded_by=request.user,
organization=organization,
word_count=len(feedback_data['feedback_content'].split())
)
created_feedbacks.append({
'id': feedback.id,
'title': feedback.title,
'metadata_included': bool(feedback.extraction_metadata)
})
return JsonResponse({
'message': f'Successfully created {len(created_feedbacks)} feedbacks',
'feedbacks': created_feedbacks
}, status=201)
except Exception as e:
return JsonResponse({'error': str(e)}, status=500)
📊 Metadata in Reports
Your metadata will appear in generated reports:
CSV Report (includes metadata summary)
Feedback ID,Title,Teacher,Metadata Fields,Custom Tags,Course Code
101,"Math Assignment",Dr. Smith,5,"urgent,final","MATH101"
102,"Essay Review",Prof. Jones,8,"revision,improved","ENG201"
JSON Report (full metadata preserved)
{
"batch": {...},
"results": [
{
"feedback": {
"id": 101,
"title": "Math Assignment",
"extraction_metadata": {
"course_code": "MATH101",
"student_id": "S123456",
"custom_tags": ["urgent", "final"],
// ... all your custom metadata
}
},
"evaluation": {...}
}
]
}
🎓 Student Context Field
The student_context field provides optional context about the student or assessment that AI should consider during evaluation:
Purpose
This field allows you to provide specific contextual information that influences how feedback should be evaluated. For example: - Grade already assigned to the student - Assessment attempt number (first try, revision, etc.) - Special circumstances or accommodations - Learning progression context
Examples
{
"student_context": "Student received B+ grade, First attempt"
}
{
"student_context": "Second submission after revision feedback"
}
{
"student_context": "Student with extended time accommodation"
}
{
"student_context": "Advanced student, grade skipping consideration"
}
AI Integration
When provided, the AI evaluation system: - Considers whether feedback is appropriate for the student's context - Adjusts evaluation expectations based on the situation - Provides context-aware assessment of feedback quality - Maintains all existing evaluation criteria while adding contextual awareness
Usage Guidelines
- Keep descriptions concise and specific
- Focus on assessment-relevant context
- Use consistent terminology across your organization
- Optional field - leave empty if no special context applies
🎯 Best Practices
1. Consistent Structure
// Good: Consistent metadata structure across feedbacks
"extraction_metadata": {
"course_info": {...},
"student_info": {...},
"grading_context": {...}
}
2. Meaningful Keys
// Good: Descriptive key names
"lms_integration": {
"course_id": "MATH101_SP24",
"assignment_type": "midterm_exam"
}
// Avoid: Unclear abbreviations
"data": {
"cid": "M101",
"at": "me"
}
3. Searchable Values
// Include searchable/filterable values
"extraction_metadata": {
"tags": ["urgent", "needs_followup", "exemplary"],
"priority_level": "high",
"semester": "Spring_2024",
"department": "Mathematics"
}
🔍 Querying Metadata
While not in the current API, you could extend it to filter by metadata:
# Future enhancement example:
# GET /api/feedbacks/?metadata.course_code=MATH101
# GET /api/feedbacks/?metadata.tags=urgent
# GET /api/feedbacks/?metadata.semester=Spring_2024
Your metadata system is incredibly flexible and can handle any additional data you need to track! 🎉