topology: schema rework

Deprecate the old topology schemas since they cannot be extended
anymore without making 'Type' field variable.

'Type' field has to be const/enum  for people to be able to find the
schema for a configuration record and for EM to be able to create a PDI
compatible DBus interface name.

The new schema for defining topology association definitions uses
'Name' property to connect the inventory items containing
the topology definitions via association definitions.

Error handling:

If the other port to 'Name' is not present, it is not an
error, the association definition will simply not be created.

This helps to represent optional components.

Power examples:

Simple, 2 fixed component. They can both declare 'Name'
```
component 1 --- PSU 1
```

One component, containing 2 components.
```
            /--- PSU 1
component 1
            \--- PSU 2
```

One generic PSU config connecting to one of various boards.
There are PSU 2 instances in this example.
The upstream component (baseboard) needs to declare a fixed 'Name' and
the PSU declares `Name`.
```
            /--- component 2 (PSU 1)
component 1
            \--- component 2 (PSU 2)

component 3 (baseboard, not present)
component 4 (baseboard, not present)
```

Containment examples:

```
Baseboard ---- Chassis variant 1
               Chassis variant 2 (not present)
```

All components besides the enclosure chassis need to know their
index/name here.

```

Baseboard 1 --+-- Chassis 1 --+
              |               |
Baseboard 2 --+-- Chassis 2 --+-- Chassis (Enclosure)
              .               .
              .               .
Baseboard N --+-- Chassis N --+
```

Implementation: next patch

Tested: next patch

References:
[1] https://github.com/openbmc/docs/blob/master/designs/physical-topology.md
[2] https://gerrit.openbmc.org/c/openbmc/entity-manager/+/81926 (Olek's
change for containment)
[3] https://gerrit.openbmc.org/c/openbmc/entity-manager/+/82408
(citysides change for cooling/cooled_by)

Change-Id: Iacf0c87dfe118ebe50e9461d519e226f10a059c5
Signed-off-by: Alexander Hansen <alexander.hansen@9elements.com>
diff --git a/docs/associations.md b/docs/associations.md
index 4dcb167..f221270 100644
--- a/docs/associations.md
+++ b/docs/associations.md
@@ -2,6 +2,86 @@
 
 Entity Manager will create [associations][1] between entities in certain cases.
 
+## Configuring Associations between Entities
+
+The configuration record has `Name` field which is used to connect 2 ports for
+an association definition.
+
+If a matching element with `Name` is not found, that is not an error, it simply
+means the component we want to associate to is not present.
+
+The `PortType` describes which association to create. This is limited to
+pre-defined values. It also defines the direction of the association.
+
+### containing Association
+
+Baseboard configuration.
+
+```json
+{
+  "Exposes": [
+    {
+      "Name": "ContainingPort",
+      "PortType": "contained_by"
+      "Type": "Port"
+    }
+  ],
+  "Name": "Tyan S8030 Baseboard"
+}
+```
+
+Chassis configuration.
+
+```json
+{
+  "Exposes": [
+    {
+      "Name": "ContainingPort",
+      "PortType": "containing"
+      "Type": "Port"
+    }
+  ],
+  "Name": "MBX Chassis"
+}
+```
+
+### powering Association
+
+Baseboard configuration. This baseboard accepts one of several generic PSUs.
+
+```json
+{
+  "Exposes": [
+    {
+      "Name": "GenericPowerPort",
+      "PortType": "powered_by"
+      "Type": "Port"
+    }
+  ],
+  "Name": "Tyan S8030 Baseboard"
+}
+```
+
+PSU configuration. This example PSU is generic and can be used on different
+servers.
+
+```json
+{
+  "Exposes": [
+    {
+      "Name": "GenericPowerPort",
+      "PortType": "powering"
+      "Type": "Port"
+    }
+  ],
+  "Name": "Generic Supermicro PSU"
+}
+```
+
+## Deprecated configuration style
+
+The configuration style described below is deprecated and superseded.
+
 ## `contained_by`, `containing`
 
 Entity Manager can model the [physical topology][2] of how entities plug into
diff --git a/schemas/exposes_record.json b/schemas/exposes_record.json
index 9196b54..1bad51f 100644
--- a/schemas/exposes_record.json
+++ b/schemas/exposes_record.json
@@ -88,7 +88,10 @@
                     "$ref": "topology.json#/$defs/Port"
                 },
                 {
-                    "$ref": "topology.json#/$defs/DownstreamPort"
+                    "$ref": "topology.json#/$defs/LegacyPort"
+                },
+                {
+                    "$ref": "topology.json#/$defs/LegacyDownstreamPort"
                 },
                 {
                     "$ref": "legacy.json#/$defs/PSUPresence"
diff --git a/schemas/topology.json b/schemas/topology.json
index 5b9a968..66c9d59 100644
--- a/schemas/topology.json
+++ b/schemas/topology.json
@@ -8,6 +8,33 @@
                 "Name": {
                     "$ref": "#/$defs/Types/Name"
                 },
+                "PortType": {
+                    "description": "This enum may be extended as described in the design",
+                    "type": "string",
+                    "enum": [
+                        "powering",
+                        "powered_by",
+                        "cooling",
+                        "cooled_by",
+                        "containing",
+                        "contained_by"
+                    ]
+                },
+                "Type": {
+                    "type": "string",
+                    "const": "Port"
+                }
+            },
+            "required": ["Name", "PortType", "Type"],
+            "type": "object"
+        },
+        "LegacyPort": {
+            "description": "deprecated schema. https://github.com/openbmc/docs/blob/master/designs/physical-topology.md",
+            "additionalProperties": false,
+            "properties": {
+                "Name": {
+                    "$ref": "#/$defs/Types/Name"
+                },
                 "Type": {
                     "description": "This enum may be extended as described in the design",
                     "type": "string",
@@ -17,8 +44,8 @@
             "required": ["Name", "Type"],
             "type": "object"
         },
-        "DownstreamPort": {
-            "description": "https://github.com/openbmc/docs/blob/master/designs/physical-topology.md",
+        "LegacyDownstreamPort": {
+            "description": "deprecated schema. https://github.com/openbmc/docs/blob/master/designs/physical-topology.md",
             "additionalProperties": false,
             "properties": {
                 "Name": {