Merge pull request #254 from RealEstateCore/dev/cbupp/memberof-relati…

…onship-and-deprecation-policy

REC TC decision 1/11/24 - resolution to issue #252 and #244

Doc/Agent/Agent.md

@@ -19,7 +19,8 @@ The human, group, or machine that consumes or acts upon an object or data. This
 
 |Name|Display name|Description|Multiplicity|Target|Properties|Writable|
 |-|-|-|-|-|-|-|
-|isMemberOf|**en**: is member of|**en**: Indicates membership in an organization. Note that componency (e.g., departments of a corporation) are expressed using the more generic Organization.isPartOf property.|0-Infinity|[Organization](Organization/Organization.md)||True|
+|isMemberOf|**en**: is member of (DEPRECATED)|**en**: Indicates membership in an organization. Note that componency (e.g., departments of a corporation) are expressed using the more generic Organization.isPartOf property. (DEPRECATED: Use memberOf going forward)|0-Infinity|[Organization](Organization/Organization.md)||True|
+|memberOf|**en**: member of|**en**: Indicates membership in an organization. Note that componency (e.g., departments of a corporation) are expressed using the more generic Organization.isPartOf property.|0-Infinity|[Organization](Organization/Organization.md)||True|
 |owns|**en**: owns|**en**: Indicates ownership of some thing, e.g., a building, an asset, an organization, etc.|0-Infinity|||True|
 
 ---

Doc/Collection/System/System.md

@@ -25,7 +25,7 @@ A System is a combination of equipment and auxiliary devices (e.g., controls, ac
 
 |Name|Display name|Description|Multiplicity|Target|Properties|Writable|
 |-|-|-|-|-|-|-|
-|includes|**en**: includes||0-Infinity|[Equipment](../../Asset/Equipment/Equipment.md)||True|
+|includes|**en**: includes||0-Infinity|||True|
 ### Inherited Relationships
 * **[Collection](../Collection.md):** documentation
 

OntologyDecisionRecords/ODR 003 Ontology Versioning.md

@@ -0,0 +1,54 @@
+# ODR 003 Ontology Versioning
+
+## Context
+
+As the ontology evolves, there is an ongoing need to align the ontology to other standards, reduce collisions, and reduce ambiguity. [Semantic Versioning](https://semver.org/) is a way to communicate to the community the types of changes that are being made to a project. 
+
+Simply renaming or removing a property or relationship would result in a breaking change, resulting in a major version update. Instead, deprecation is preferred as a way to signal to the community that a change will be made in the next major update, and allow time for the community to align to the changes.
+
+DTDL does not provide a consistent way to annotate that a model's contents have been deprecated. As a result, we need a consist way to flag that a model's properties or relationships have been deprecated.
+
+Graph validity will be a test of if a change is a major or minor change. If any hypothetical graph that can be represented before a change is still valid after the change, the change is considered non-breaking from the ontology's perspective. Consider the 2 following examples:
+
+1. **Major Change Example**: A model's relationship is modified that adds a restriction to a relationship's target.
+1. **Minor Change Example**: A model's relationship is modified so that the target restrictions are removed.
+
+## Decisions
+
+### Versioning
+
+1. RealEstateCore will follow a versioning scheme of `MAJOR.MINOR`
+   - Breaking changes will require a `MAJOR` version update
+   - Minor changes will require a `MINOR` version update
+
+1. RealEstateCore defines breaking changes as:
+   - Remove deprecated models
+   - Remove deprecated model content
+   - Remove models (without deprecation)
+   - Remove model content (without deprecation)
+   - Restricting the target of relationships
+
+1. RealEstateCore defines minor changes as:
+   - Adding new models
+   - Adding new model content
+   - Modifying content descriptions and comments
+   - Deprecate model content
+   - Broaden the target of relationships
+
+1. RealEstateCore has not released patches in the past. If there is a need for a `PATCH` in the future, this ODR will be updated to reflect decisions about `PATCH` versioning.
+
+1. RealEstateCore will use deprecation to reduce excessive `MAJOR` version increments
+
+1. RealEstateCore will clean up content deprecation during `MAJOR` version increments
+
+### Annotating Deprecation
+
+1. We will append ` (DEPRECATED)` to the content's display name.
+
+1. We will append ` (DEPRECATED: <recommendation going forward>.)` to the content's description. This should include a recommendation on how to migrate going forward.
+
+## Consequences
+
+1. Minor version updates could accumulate several deprecations, that could result in confusion in the community on which properties/relationships to use. Each deprecation should clearly notate recommendations.
+
+1. Major version updates should include the removal of the deprecated content.

Source/DTDLv2/Brick/Collection/System/System.json

@@ -8,7 +8,6 @@
         "en": "includes"
       },
       "name": "includes",
-      "target": "dtmi:org:brickschema:schema:Brick:Equipment;1",
       "writable": true
     }
   ],

Source/DTDLv2/RealEstateCore/Agent/Agent.json

@@ -81,10 +81,11 @@
     {
       "@type": "Relationship",
       "description": {
-        "en": "Indicates membership in an organization. Note that componency (e.g., departments of a corporation) are expressed using the more generic Organization.isPartOf property."
+        "en": "Indicates membership in an organization. Note that componency (e.g., departments of a corporation) are expressed using the more generic Organization.isPartOf property. (DEPRECATED: Use memberOf going forward)"
       },
+      "comment": "DEPRECATED: Use memberOf going forward",
       "displayName": {
-        "en": "is member of"
+        "en": "is member of (DEPRECATED)"
       },
       "name": "isMemberOf",
       "target": "dtmi:org:w3id:rec:Organization;1",
@@ -100,6 +101,18 @@
       },
       "name": "owns",
       "writable": true
+    },
+    {
+      "@type": "Relationship",
+      "description": {
+        "en": "Indicates membership in an organization. Note that componency (e.g., departments of a corporation) are expressed using the more generic Organization.isPartOf property."
+      },
+      "displayName": {
+        "en": "member of"
+      },
+      "name": "memberOf",
+      "target": "dtmi:org:w3id:rec:Organization;1",
+      "writable": true
     }
   ],
   "description": {