Expand FAIR Mappings Schema documentation and model

Enhanced the about and index documentation to provide background, usage examples, and detailed schema overview. The schema YAML was significantly extended: new enums for source and mapping types, expanded slots for provenance, licensing, and source metadata, and new classes for Agent, Person, Organization, Software, and Source. The MappingSpecification class now supports richer metadata and explicit subject/object source modeling, aligning with FAIR principles and community best practices.

Author: matentzn

docs/about.md

@@ -1,3 +1,35 @@
-# About fair-mappings-schema
+# About FAIR Mappings Schema
 
-A basic metadata schema for FAIR mapping specifications
+## Background
+
+Semantic mappings between ontologies, vocabularies, databases, and other data sources are essential for data integration and interoperability. However, these mappings are often poorly documented, difficult to discover, and lack the metadata needed to assess their quality and provenance.
+
+The FAIR Mappings Schema addresses this gap by providing a minimal but comprehensive metadata model for describing mapping specifications in a way that adheres to [FAIR principles](https://www.go-fair.org/fair-principles/) (Findable, Accessible, Interoperable, Reusable).
+
+## RDA FAIR Mappings Working Group
+
+This schema is developed by the [RDA FAIR Mappings Working Group](https://mapping-commons.github.io/rda-fair-mappings/), which brings together researchers, practitioners, and standards developers to establish best practices for creating and sharing FAIR mappings.
+
+The working group aims to:
+
+- Define metadata standards for mapping specifications
+- Promote interoperability between different mapping formats
+- Build a community around mapping best practices
+
+## Schema Design
+
+The schema is built using [LinkML](https://linkml.io/), a flexible modeling language that generates multiple representations including JSON Schema, Python dataclasses, and RDF/OWL.
+
+### Core Concepts
+
+- **MappingSpecification**: The central class representing a mapping between sources
+- **Source**: A data source (ontology, database, vocabulary, schema, or API) from which entities are drawn
+- **Agent**: An entity (person, organization, or software) that contributes to creating mappings
+
+## Contributing
+
+Contributions are welcome. Please visit the [GitHub repository](https://github.com/mapping-commons/fair-mappings-schema) to report issues or submit pull requests.
+
+## License
+
+This project is licensed under Apache-2.0.

docs/index.md

@@ -1,5 +1,52 @@
-# fair-mappings-schema
+# FAIR Mappings Schema
 
-A basic metadata schema for FAIR mapping specifications
+A minimal metadata schema for describing FAIR mapping specifications between data sources.
 
-- Auto-generated [schema documentation](elements/index.md)
+## Overview
+
+The FAIR Mappings Schema provides a standardized way to describe mappings between different data sources such as ontologies, databases, vocabularies, and schemas. It captures essential metadata about mapping specifications including provenance, licensing, and the sources being mapped.
+
+This schema is developed as part of the [RDA FAIR Mappings Working Group](https://mapping-commons.github.io/rda-fair-mappings/) effort to improve the findability, accessibility, interoperability, and reusability of semantic mappings.
+
+## Key Features
+
+- **Source Description**: Describe subject and object sources with their types, versions, and access URLs
+- **Provenance Tracking**: Record authors, creators, reviewers, and publication dates
+- **Mapping Specification system agnostic**: Can be used, or easily mapped to, SSSOM, R2RML, RML, SPARQL, YARRRML, XSLT, SHACL, and other mapping formats.
+
+## Example
+
+```yaml
+---
+publication_date: "2024-01-15"
+license: CC-BY-4.0
+version: "1.0.0"
+description: Mappings between disease ontologies DO and MONDO
+type: sssom
+mapping_method: manual curation
+documentation: https://example.org/do-mondo-mappings/docs
+content_url: https://example.org/mappings/do-mondo.sssom.tsv
+subject_source:
+  name: Disease Ontology
+  version: "2024-01-01"
+  type: ontology
+  documentation: https://disease-ontology.org/
+  content_url: http://purl.obolibrary.org/obo/doid.owl
+  content_type: application/rdf+xml
+object_source:
+  name: Mondo Disease Ontology
+  version: "2024-01-10"
+  type: ontology
+  documentation: https://mondo.monarchinitiative.org/
+  content_url: http://purl.obolibrary.org/obo/mondo.owl
+  content_type: application/rdf+xml
+```
+
+## Documentation
+
+- [Schema Elements](elements/index.md) - Documentation for all schema classes, slots, and enums.
+
+## Quick Links
+
+- [RDA FAIR Mappings Working Group](https://mapping-commons.github.io/rda-fair-mappings/)
+- [GitHub Repository](https://github.com/mapping-commons/fair-mappings-schema)