diff --git a/Doc/Agent/Agent.md b/Doc/Agent/Agent.md index 46b1af525..0f2425e5d 100644 --- a/Doc/Agent/Agent.md +++ b/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| --- diff --git a/Doc/Collection/System/System.md b/Doc/Collection/System/System.md index 6671ffc3b..abe279472 100644 --- a/Doc/Collection/System/System.md +++ b/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 diff --git a/OntologyDecisionRecords/ODR 003 Ontology Versioning.md b/OntologyDecisionRecords/ODR 003 Ontology Versioning.md new file mode 100644 index 000000000..795294543 --- /dev/null +++ b/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: .)` 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. \ No newline at end of file diff --git a/Source/DTDLv2/Brick/Collection/System/System.json b/Source/DTDLv2/Brick/Collection/System/System.json index 4bfe4bde6..400d1ee28 100644 --- a/Source/DTDLv2/Brick/Collection/System/System.json +++ b/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 } ], diff --git a/Source/DTDLv2/RealEstateCore/Agent/Agent.json b/Source/DTDLv2/RealEstateCore/Agent/Agent.json index 548e48a97..2b3a832ba 100644 --- a/Source/DTDLv2/RealEstateCore/Agent/Agent.json +++ b/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": {