Conventions

Owned by Tom Coppeto
Last updated: Nov 14, 2013
2 min read

Summary

Okapia conventions for Type identifiers.

Types

Types define a set of meta information along with it's identification. The identification components of a Type are:

  • authority
  • namespace
  • identifier

The rest of the information found in a Type is not part of its unique identification. Two Types are equal if their authority, namespace, and identifier are equal. Nothing else matters. It also does not matter what Type implementation is used as long as it obeys the equality requirement. 

Type identifiers are never displayed to users, so it doesn't really matter how ugly they are, but you want to have some scheme to organize, parse, and recognize in a log file. The Type name and label provide displayable content. 

Authority

The authority is the name of the entity that has assigned the identifier. In the case of record Types, the authority is also the owner of the OsidRecord interface to which the record Type identifies. 

We use domain names to represent the authority. Because this is the big uniquifier, it's helpful to key off of some global namespace such as the domain name system. For long-lived Types that you expect others to adopt, the domain name should be stable to avoid gratuitous changes in Type identifiers due to re-orgs.

Namespaces

The namespace and identifier play off each other to form something unique within an authority. We push much of that uniqueness into the identifier and keep the namespaces simple.

Our namespaces are:

  • records: Types assigned to OsidRecord agreements
  • genera: Types assigned to OsidObject genus Types
  • <OsidPrimitive>: Types assigned to OsidPrimitives

Identifiers

For record Types, the uniqueness includes the path to the OsidRecord, e.g. repository/Asset/Book. This keeps a correlation between the Type and the OsidRecord interface, e.g. osid.repository.records.AssetBookRecord.

The same for genus Types, e.g. repository/Asset/Novel. 

Serialized Formats

Types are serializable and good Type implementations will offer a deserializing function to go back and forth. As it is convenient to combine all three components together for the purpose of logging, storing, or hard coding Type identifiers in various places, the question of which format arises.

Basic

The basic format we use is: 

<namespace>:<identifier>@<authority>.

This is what net.okapia.osid.primordium.type.BasicId supports. Example:

records:repository/Asset/Book@okapia.net

URN

We also use an unregistered URN namespace to capture Type identifiers that's a bit easier to manage in tables and spreadsheets. 

urn:osid:<authority>:types:<kind>:<namespace>:<identifier>

This is what net.okapia.osid.primordium.type.URNId supports. Example:

urn:osid:okapia.net:types:records:repository:Asset:Book

Which Format?

It's just a matter of taste. Make your own if you'd like. But here's a rule of thumb to follow with Type implementations:

MyType.valueOf("myFormat").equals(YourType.valueOf("yourFormat")) == true;

In making new serializable formats, the format must be able to distinguish among the three Type identification components so it can be parsed back into the same Type. If you don't like the format of the Types coming from an OSID Provider, through up a Type-interceptor OSID Adapter and change them on the way out. You might want to do this anyway if you want the meta information and the OSID Provider isn't supplying it.

Can I just Use an External Tool and Not Worry About Type Implementations?

That also works.

See Also

 


Copyright © 2014 Okapia.