Types Versioning in Object Model Endpoints

The Info Model Service of the Ability Platform will accept a request with or without a type version for any given endpoint.

The following use case describes IM service behavior for POST and PUT requests, with and without a type version specified in the payload.

Info Model API POST /objects endpoint

When a type without a version is present in the request payload, the info model service tries to create a model using the latest type version implementation.

The IM service will:

• check to see if a model exists (with any type version). If a model exists, the IM service rejects the request.

• find the latest type version via the TDR GET /modelDefinitions/{modelId}/types/{typeId}/versions endpoint.

• add the latest type major version to the payload.

• proceed with an IM POST /objects request, as in the design base.

Info Model API PUT /objects/{objectId}/models/{modelId} endpoint

When a type without a version is present in the request payload, the info model service tries to update the existing model only if typeId has not been changed, and the type is of the latest type major version. Changing the type major version or typeId during a model update should be a specific operation that is explicitly triggered.

• A user must change a type (including from one major version to another if they are compatible, or to a different typeId/subtype) only with an explicit type version property present in the request. Otherwise the client may not be aware that by updating an object model there will be a new major version.

• A user should change an incompatible type by deleting and recreating the object model (also possible with no version property present in the payload). The migration logic is domain-specific, requiring strict adherence to the guidance set forth above.

When a type with a major version is present in the request payload, the information model service tries to update the object using that typeId and the latest version with the specified major part.

• Explicit type version upgrades/downgrades are allowed.
• Changing to different type (typeId and version) is allowed.

Additional validations:

• IM service checks if a model exists (with any typeId and version or with typeId and latest version if not specified in the payload). If a model does not exist, the IM service rejects the request.

• IM service compares the typeId from request payload to the existing model's typeId:

  • When typeIds are matching, and type major version was not specified in request payload:

    • IM service finds the latest type version via the TDR GET "/modelDefinitions/{modelId}/types/{typeId}/versions" or the GET "/modelDefinitions/{modelId}/types/{typeId}" endpoint (depending on the needs).

    • IM service compares the latest type major version to the existing model's type major version:

      • When major versions are matching - the service proceeds with an IM PUT.
      • When major versions are different - the service rejects the request with error details: "Object model already exists for <versioned typeId for existing object model here>, while current latest version is <latest version here>. Only explicit upgrade/downgrade to different major version type is supported. Please provide type@version in payload".

    • IM service adds the latest type major version to the payload.

  • When typeIds are not matching, and type's major version was not specified in request payload - the service rejects the request with error details:
    "Optional type version is not supported for switch type. Please provide type@MajorVersionNumber in payload".

• IM service proceeds with an IM PUT, as in the design base.