Update documentation

Author: David Andersson

docs/source/examples/relationship/many_to_many.rst

@@ -14,8 +14,8 @@ assigned to a project.
     `SQLAlchemy Many to Many <https://docs.sqlalchemy.org/en/13/orm/basic_relationships.html#many-to-many>`_
       SQLAlchemy documentation for many to many relationships.
 
-The following example defines a many to many relationship between *Employee*
-and *Project*:
+The following example defines a many to many relationship between
+:samp:`Employee` and :samp:`Project`:
 
 .. literalinclude:: ../../../../examples/relationship/many_to_many/example-spec.yml
     :language: yaml
@@ -39,3 +39,42 @@ OpenAlchemy will generate the following typed models:
 .. literalinclude:: ../../../../examples/relationship/many_to_many/models_auto.py
     :language: python
     :linenos:
+
+Custom Association Schema
+-------------------------
+
+OpenAlchemy also supports customization of the association schema that
+implements the many-to-many relationship. This means that the schema can be
+changed to include, for example, a column tracking when the association was
+established.
+
+.. seealso::
+
+    :ref:`custom-association`
+      OpenAlchemy documentation for many to many relationships with a custom
+      association schema.
+
+The following example defines a schema for the association:
+
+.. literalinclude:: ../../../../examples/relationship/many_to_many/pre-defined-example-spec.yml
+    :language: yaml
+    :linenos:
+
+The following file uses OpenAlchemy to generate the SQLAlchemy models:
+
+.. literalinclude:: ../../../../examples/relationship/many_to_many/pre_defined_models.py
+    :language: python
+    :linenos:
+
+The SQLAlchemy models generated by OpenAlchemy are equivalent to the following
+traditional models file:
+
+.. literalinclude:: ../../../../examples/relationship/many_to_many/pre_defined_models_traditional.py
+    :language: python
+    :linenos:
+
+OpenAlchemy will generate the following typed models:
+
+.. literalinclude:: ../../../../examples/relationship/many_to_many/pre_defined_models_auto.py
+    :language: python
+    :linenos:

docs/source/technical_details/relationships.rst

@@ -499,3 +499,50 @@ dictionary::
 
 Indicating that the project is being worked on by the employees with an id of
 *1* and *3*.
+
+.. _custom-association:
+
+Custom Association Schema
+-------------------------
+
+OpenAlchemy supports customizing the association schema. This is useful to,
+for example, add columns tracking when the association between two objects
+was first established.
+
+To define a custom association schema, define a schema that has an
+:samp:`x-tablename` that is the same as the :samp:`x-secondary` value of the
+many-to-many relationship. The following rules apply to the schema (which are
+enforced):
+
+#. Any properties that are primary keys must also be one of the properties
+   establishing a foreign key relationship to the child or the parent.
+#. At most 2 primary key properties can be defined.
+#. The :samp:`type`, :samp:`format` and :samp:`maxLength` of the foreign key
+   property establishing one side of the many-to-many relationship must match
+   the primary key property of the object on that side of the relationship
+   (including whether they are defined).
+
+OpenAlchemy will check for any missing foreign key properties and add them in
+automatically. For example, if an association only defines one side of a
+many-to-many relationship, OpenAlchemy will automatically generate a property
+for the other side.
+
+Custom association schemas can define any other properties that are not
+primary keys. Note the following to ensure smooth operations:
+
+* Any additional columns should somehow be generated by the server, for
+  example, through a server default of the current time. This ensures that
+  SQLAlchemy can automatically generate entries into the table to establish a
+  many-to-many link between two objects.
+* It is possible to define relationships to the parent and child objects.
+  However, not all of the usual relationship functionality is supported, for
+  more information check here:
+  `SQLAlchemy association object documentation <https://docs.sqlalchemy.org/en/13/orm/basic_relationships.html#association-object>`_
+
+The following shows an example where the :samp:`Employee` side of the
+association schema has been defined. OpenAlchemy will automatically generate
+the :samp:`Project` side before constructing the model.
+
+.. literalinclude:: ./relationships/many_to_many/custom_association.yaml
+    :language: yaml
+    :linenos:

docs/source/technical_details/relationships/many_to_many/custom_association.yaml

@@ -0,0 +1,34 @@
+Project:
+  type: object
+  x-tablename: project
+  ...
+  properties:
+    id:
+      type: integer
+      x-primary-key: true
+    ...
+Employee:
+  type: object
+  x-tablename: employee
+  ...
+  properties:
+    id:
+      type: integer
+      x-primary-key: true
+    ...
+    projects:
+      type: array
+      items:
+        allOf:
+          - "$ref": "#/components/schemas/Project"
+          - x-secondary: employee_project
+EmployeeProject:
+  type: object
+  x-tablename: employee_project
+  ...
+  properties:
+    employee_id:
+      type: integer
+      x-primary-key: true
+      x-foreign-key: employee.id
+    ...

examples/relationship/many_to_many/pre_defined_models_traditional.py

@@ -4,14 +4,6 @@
 Base = declarative_base()
 
 
-employee_project = sa.Table(
-    "employee_project",
-    Base.metadata,
-    sa.Column("project_id", sa.Integer, sa.ForeignKey("project.id")),
-    sa.Column("employee_id", sa.Integer, sa.ForeignKey("employee.id")),
-)
-
-
 class Project(Base):
     """A large sized business objective."""