Doc update & deprecation

README.md

@@ -328,15 +328,15 @@ transformations directly in a programming language or library like Python or Pan
 even for the coding use case, the LinkML Transformer framework can be useful as a standard way
 of *documenting* transformations).
 
-Currently the main use case for this framework is *mostly isomorphic* transformations, with lightweight
+Currently, the main use case for this framework is *mostly isomorphic* transformations, with lightweight
 manipulations. These lend themselves well to a declarative framework. Uses cases that are a particularly good fit
 involve mapping between data-dictionary like standards, with large numbers of metadata elements, where these
 elements can often be mapped one-to-one, or with simple manipulations (e.g. unit conversions).
 
 The origins lie partly in the SSSOM standard, which is intended as an ultra-simple way of specifying
 precise mappings between *entities* (e.g. schema.org Person is the same as DBPedia person). We observed
 that many people wanted to extend the language to perform more complex mappings. To address this, we
-help a workshop at the Biocuration conference in Padua, Italy in 2022.
+helped host a workshop at the Biocuration conference in Padua, Italy in 2022.
 
 - [Discussion](https://github.com/orgs/linkml/discussions/1829)
 - [SSSOM paper](https://academic.oup.com/database/article/doi/10.1093/database/baac035/6591806)

mkdocs.yml

@@ -10,5 +10,6 @@ nav:
   - Index: index.md
   - Specification:
       Compliance Suite: specification/compliance.md
+      Creating a Transform YAML: specification/transform_yaml.md
 site_url: https://cmungall.github.io/linkml-transformer/
 repo_url: https://github.com/cmungall/linkml-transformer/

src/linkml_transformer/datamodel/transformer_model.yaml

@@ -44,6 +44,9 @@ classes:
     class_uri: linkml:Any
 
   SpecificationComponent:
+    description: >-
+        An abstract grouping for classes that provide a specific kind of specification of a transformation
+        component.
     abstract: true
     attributes:
       description:
@@ -64,15 +67,24 @@ classes:
 
   TransformationSpecification:
     is_a: SpecificationComponent
-    description: A collection of mappings between source and target classes
+    description: >- 
+      A metadata object that contains collections of class, slot, and enum element derivations as well
+      as metadata about the transformation event like the location of the source and target schemas
+      the human readable title of the transform and an optional unique identifier for the transform.
     tree_root: true
     attributes:
       id:
-        # identifier: true
-        description: Unique identifier for this transformation specification
+        description: >-
+          Unique identifier for this transformation specification.  This is an optional attribute, however
+          it is recommended that a unique identifier be provided for each transformation specification.  Unique
+          identifiers allow for keeping track of the application of a transform in downstream systems and prevent
+          double application of a transform which may cause damage to a datastore that has progressed past the 
+          initial transform run.
         slot_uri: schema:identifier
       title:
-        description: human readable title for this transformation specification
+        description: >- 
+          A human readable title for this transformation specification. Best practice is to use a title that 
+          incorporates the source schema and the target schema version.
         slot_uri: dcterms:title
       prefixes:
         description: maps prefixes to URL expansions
@@ -234,6 +246,12 @@ classes:
         range: string
       stringification:
         range: StringificationConfiguration
+      deprecated:
+        range: boolean
+        description: >-
+          If a slot is deprecated, it will not be included in the target schema yaml file, and all references
+          in the source schema to that slot will be removed.  However, the deprecated slot will be added to an
+          "obsolete" yaml file that will be generated along with the target schema yaml file.
 
   EnumDerivation:
     is_a: ElementDerivation

src/linkml_transformer/transformer/object_transformer.py

@@ -55,6 +55,13 @@ def index(self, source_obj: Any, target: str = None):
         else:
             self.object_index = ObjectIndex(source_obj, schemaview=self.source_schemaview)
 
+    def deprecate(self, source_obj: Any):
+        """
+        Deprecate an object.
+
+        :param source_obj: source data structure to be deprecated
+        """
+
     def transform(
         self,
         source_obj: OBJECT_TYPE,
@@ -65,8 +72,9 @@ def transform(
         Transform a source object into a target object.
 
         :param source_obj: source data structure
-        :param source_type: source_obj instantiates this (may be class, type, or enum)
-        :param target_type: target_obj instantiates this (may be class, type, or enum)
+
+        :param source_type: source_obj instantiates this (source_type value may be class, type, or enum)
+        :param target_type: target_obj instantiates this (target_type value may be class, type, or enum)
         :return: transformed data, either as type target_type or a dictionary
         """
         sv = self.source_schemaview