data-model

name	data-model
description	Add or update a dart_mappable data model in lib/src/models/content/, including adding format validation, regenerating code, and adding tests. Use when adding a new content type or modifying an existing model's fields.
argument-hint	["data-model-description or existing-data-model"]

Data model skill

Add or update a typed content model in this project. Follow the established conventions below as much as possible.

Before starting

1. If updating an existing model, read the model file, its source YAML or JSON file(s), and its test group first.
2. If adding a new model, identify which page will use it and the structure of the YAML file it will load from and map to. If the YAML file doesn't exist, ask the user to create and reference it or provide information about its expected structure.

Model file conventions

All data models live in the lib/src/models/content directory and should roughly follow this general structure:

import 'package:dart_mappable/dart_mappable.dart';

import 'content_validation.dart';

part '<filename>.mapper.dart';

/// Doc comment: What this model represents and where it's loaded from.
///
/// Expected data format:
/// - `field_name`: Description and constraints of the expected value.
@MappableClass()
class ModelName with ModelNameMappable {
  ModelName({
    required this.fieldOne,
    required this.fieldTwo,
    this.optionalField,
  }) {
    // Validate all fields beyond their Dart type.
    checkFormat(isNotBlank(fieldOne), 'field_one must be a non-empty string.');
    // For optional fields, only validate when present:
    if (optionalField case final optionalField?) {
      checkFormat(isNotBlank(optionalField), 'optional_field must be a non-empty string.');
    }
  }

  /// Each field should have a doc comment that follows Effective Dart.
  final String fieldOne;

  // Use `@MappableField` when the YAML key differs from the Dart field name.
  @MappableField(key: 'field_two')
  final String fieldTwo;

  // Optional fields are nullable and not marked `required` in the constructor.
  final String? optionalField;

  // Every model must have this static factory. Use the generated mapper.
  static ModelName fromJson(Map<String, Object?> json) => ModelNameMapper.fromMap(json);
}