sources

type DataSourceConfig struct {
	// Core identification (required)
	// ID identifies the data source. Convention: < 1000 = official, >= 1000 = custom
	ID int `yaml:"id"`

	// Parent is the directory or URL containing SFGA files for this source.
	// Auto-detected: starts with http:// or https:// = URL, otherwise = directory
	// SFGA files are matched by pattern: {4-digit-ID}*.zip or {ID}*.zip
	// Examples:
	//   - http://opendata.globalnames.org/sfga/latest/
	//   - /home/user/data/sfga/
	//   - ~/data/sfga/
	Parent string `yaml:"parent"`

	// Titles and description (override SFGA if needed)
	Title       string `yaml:"title,omitempty"`       // Override SFGA col__title
	TitleShort  string `yaml:"title_short,omitempty"` // Fallback: col__alias → truncate col__title
	Description string `yaml:"description,omitempty"` // Override SFGA col__description

	// URLs (override SFGA if needed)
	HomeURL string `yaml:"home_url,omitempty"` // Override SFGA col__url
	DataURL string `yaml:"data_url,omitempty"` // Download URL (not in SFGA)

	// Curation level (quality indicators)
	IsCurated         bool `yaml:"is_curated,omitempty"`         // Manually curated by experts
	IsAutoCurated     bool `yaml:"is_auto_curated,omitempty"`    // Automatically validated
	HasClassification bool `yaml:"has_classification,omitempty"` // Has hierarchical taxonomy

	// Outlink configuration (for generating links to original records)
	IsOutlinkReady  bool   `yaml:"-"`                           // Can generate outlinks
	OutlinkURL      string `yaml:"outlink_url,omitempty"`       // URL template with {} placeholder
	OutlinkIDColumn string `yaml:"outlink_id_column,omitempty"` // table.column format (e.g., "taxon.col__id", "name.col__alternative_id")

	// PreferFlatClassification indicates that this source should use
	// flat classification (no hierarchy) when imported.
	PreferFlatClassification bool `yaml:"prefer_flat_classification"`
}

type FileMetadata struct {
	ID          int    // Extracted from filename
	Version     string // Extracted from filename (if present)
	ReleaseDate string // Extracted from filename in YYYY-MM-DD format (if present)
	IsURL       bool   // True if file is a URL
}

type Sources interface {
	Load() (*SourcesConfig, error)
}

type SourcesConfig struct {
	// DataSources is the list of data sources to import.
	DataSources []DataSourceConfig `yaml:"data_sources"`

	// Warnings holds non-fatal validation warnings (not serialized)
	Warnings []ValidationWarning `yaml:"-"`
}

type ValidationWarning struct {
	DataSourceID int    // ID of the data source
	Field        string // Field name that has the issue
	Message      string // Description of the issue
	Suggestion   string // How to fix it
}