EntityId Requirements

{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}

About

This page is for working out the requirements and design decisions for any changes to Higgins EntityIds in the migration from the Context Data Model 1.0 to the Context Data Model 1.1. Some background discussion is here: IdAS EntityId Requirements Discussion Summary.

Current EntityId Definition in Context Data Model 1.0

1. Is of type [need info here].
2. Has cardinality 0..1
3. MUST be Context-unique; MAY be globally unique.
4. Is always exposed as an Attribute.
5. Exposes no information about mutability.

Proposed Definitions for Higgins 1.1

Entity:

1. An Entity is a node in the graph described by the Higgins Context Data Model.
2. An Entity is identified by 0..n EntityIds (vs. 0..1 in Higgins 1.0)
3. At least one EntityId of an Entity SHOULD be immutable, i.e., serve as a persistent reference to the Entity within that Context (forever). However because Higgins does not control Contexts or Context policies, the CDM must be prepared that an identifier for an Entity MAY be mutable, i.e., may be reassigned in that Context to reference a different Entity.

EntityId:

1. An EntityID is of type String (if the EntityId is not an Attribute of the Entity) else of type IAttribute (if the EntityId is also an Attribute of the Entity)
2. An EntityId MUST be locally unique within the Context.
3. An EntityId MAY be globally unique (GUID)
4. An EntityId MAY be exposed as an Attribute. If it is the Attribute Type MUST be marked as a higgins:synonym
5. An Entity MAY have a single cannonical EntityId that MUST be immutable

Proposed Changes in Context Data Model 1.1

#1: Not Require EntityId to be Exposed as an Attribute

The proposed change is to make it OPTIONAL to expose EntityId as some kind of Attribute. Contexts that do not want to expose the EntityId can omit it from the list of Attributes for an Entity. Note: if the EntityId is mutable, it SHOULD be exposed as an Attribute so it can be modified.

#2: Add a higgins:synonym Attribute to higgins.owl

For those Context Provider developers who wish to explicitly tag certain Attributes as being capable of being used as an alternative identifier for this Entity (i.e. it uniquely at LEAST within the containing Context identifies this Entity).

For example, if the developer wished to declare a "mobile" telephone number attribute as being a synonym to whatever kind of identifier getEntityId() returns, they would, in their Attribute Definition define their new mobile attribute as a sub-property of higgins:synonym. For example:

:mobile
     a       owl:DatatypeProperty ;
     rdfs:range xsd:string ;
     rdfs:subPropertyOf higgins:synonym .

[well, in practice the range would likely be a syntax restriction on xsd:string, not a plain old xsd:string, but fixing that would complicate the example]

#3: Changes to EntityID definition

• The canonical EntityId (if it exists) is immutable

Proposed Changes to IdAS API for Higgins 1.1

public Object[] IEntity.getEntityIds();

This method returns an array of EntityIds that uniquely identify the Entity within the Context. Each Object is either

• a String (if the EntityId is not an Attribute of the Entity)
• an IAttribute (if the EntityId is also an Attribute of the Entity)

public Object IEntity.getCanonicalEntityId();

This method returns the "canonical" EntityId, i.e. the preferred one. The returned object is either a String or an IAttribute. The context provider guarantees that this EntityId is immutable. Returns null if this Entity has no Cannonical EntityId

public IEntity IContext.getEntity(String);

This method already exists today. There is no change to it. It looks up an IEntity based on a String which is not an Attribute of the Entity.

public Iterator IContext.getEntities(IFilter);

This method already exists today. There is no change to it. It looks up IEntitys based on an IFilter, which can select them by Attribute Values.

public IAttributeModel.isEntityId();

Returns true, if IAttributes that use this IAttributeModel also act as EntityIds. These IAttributes may be returned by the above IEntity.getEntityIds() method.

public IAttributeModel.isMutable();

Returns true, if IAttributes that use this IAttributeModel are mutable, i.e. if its IAttributeValues can be changed/added/removed.

Example Using Proposed Changes

The following diagram shows three Entities: two ordinary Entities and one Entity Class (higgins:Person):

• The Context Provider developer has defined three simple Attributes: "ssn", "mobile", and "shoe-size".
• The developer chose to use the SSN as the canonical EntityId
• The developer chose the option to "repeat" the canonical EntityId value as the value of the "ssn" Attribute.
• Although it is not shown in the above diagram, the developer has defined two of these (SSN & mobile) as being Synonym Attributes.
• Just to show off to his boss, the developer defined a complex Attribute called "knows" and used it to link the entity on the left with the entity on the right by referring to the right-most entities canonical (and hopefully immutable) entityId.

Using IdAS...

• Calling IEntity.getCanonicalEntityId() on the Entity at the left will return the (canonical) EntityId value 033568888.
• Calling IEntity.getCanonicalEntityId() on the Entity at the right will return the (canonical) EntityId value 034898786.
• Calling IEntity.getEntityIds() on the Entity at the left will return a list of these two IAttributes:
  • mobile with value +16175137924
  • ssn with value 033568888
• Calling IEntity.getAttribute(<knows>) on the Entity at the left will return the Entity on the right [some liberties taken here for brevity]