8.2.3. Model identification
As stated above, a model is a collection of types. These types are organised hierarchically. Context (types) contain context types and many others, role (types) contain property types, etc. The hierarchy begins with a context type that has exactly the same identifier as the model itself.
Models can be authored by anyone, all over the world. Models can also be used by anyone, in any combination. This requires model identifiers to be globally unique. We do not assume there will be a dedicated global register of models, hence an author cannot check whether the model name he intends to use is unique by comparing it to existing models. Instead, we need to provide a method for constructing a globally unique identifier.
Model names need to be communicable, too, for example because authors may want to advertise their models. This precludes Globally Unique Identifiers (GUIDs) as defined in rfc4122, A Universally Unique IDentifier (UUID) URN Namespace. These identifiers are anything but human-readable, are very hard to remember and so do not lend them for human communication.
Instead, we construct a custom URI scheme with the name model. rfc3986 states: Many URI schemes include a hierarchical element for a naming authority so that governance of the name space defined by the remainder of the URI is delegated to that authority. For Perspectives, we will rely on the domain name system (DNS) as the authority that governs name spaces for the internet, to ensure that model names are unique.
What identifiers can we construct under this scheme? Here is an example of a full URI:
model://perspectives.domains#System
model is the scheme name, separated with a colon (as prescribed) from the identifier constructed under the scheme. The authority has to be delimited up front by two forward slashes and at the end by another forward slash, a question mark or a hash sign.
We forego the possibility to end the authority with a forward slash or a question mark: we just use the hash sign. This decision is heavily influence by the fact that forward slashes cannot be part of Couchdb file names.
In the model scheme, the authority itself has no user- or port information. Following the authority is the local name for the model. This name must start with an upper case character and must be unique in the domain identified by the authority to make the URI unique.
Referring back to rfc3986 we define this syntax for the identifiers under the model scheme:
Identifier = “//” reg-name “/” segment-nz-nc
A reg-name (registered name) intended for lookup in the DNS uses the syntax defined in Section 3.5 of RFC1034 and Section 2.1 of RFC1123. A segment-nz-nc is a non-zero-length segment without any colon ":". We add the constraint that it must start on an upper case character.
Our model scheme has the advantage that it can be easily mapped onto a URL. As a matter of fact, the identifiers constructed under the model scheme are a subset of those that can be constructed under the https scheme (after substituting model by https). This means we can locate a unique resource by means of a model identifier (more on this below).
8.2.3.1. Mapping URIs to URLs
We use a simple mapping from URI to the URL where the DomeinFile (the compiled model text) can be found. The authority (a reg-name) is used thrice:
-
Once as the authority of a URL in the https scheme;
-
Once as part of a single step in the path of that URL. That single step is prefixed with “models_” and all dots are replaced by underscores. It identifies the Couchdb database that holds the DomeinFile;
-
Once as part of the actual file name that the DomeinFile is stored under (see DomeinFile Identifiers.)
For example:
model://perspectives.domains#System
maps to:
Another example:
model://social.perspectives.domains#System
maps to:
In this way, we can have multiple hierarchical levels in our model namespaces, while always mapping them to a location in a simple domain (By which we mean: a top level domain, such as “com” and one subdomain (such as “google”)).
8.2.3.2. Model stores
The Perspectives Distributed Runtime uses Pouchdb, that relies on the conventions of Couchdb, to access resources. For our purposes, this means that a webserver must map URLs of the form https://perspectives.domains/models_social_perspectives_domains/social_perspectives_domains-System.json
to a database in a Couchdb installation (for example, a local installation). It is up to the webserver to provide that mapping (But there are three restrictions. See Mapping Model Identifiers to Storage Locations). However, we suggest a simple scheme that just uses the first step of the path as the database name. In this case, the json resource might be retrieved from Couchdb using this string: models_social_perspectives_domains/perspectives_domains-System.json
. That is, we want the resource perspectives_domains-System.json in the database models_social
.
According to its documentation, Couchdb allows forward slashes in its database names. In the practice of version 3.1.0 this runs into problems. Hence we replace slashes by underscores.
8.2.3.3. Storage service providers
Suppose Perspect BV io, owner of the domain perspectives.domains
would provide storage services to third parties, how would it handle them? It could offer an author like me to use a subspace of their namespace, e.g. joopringelberg.perspectives.domains
. I could then create a model with this name: model://joopringelberg.perspectives.domains#JoopsModel
. This would map to the following url: https://perspectives.domains/models_joopringelberg_perspect_perspectives_domains/joopringelberg_perspect_perspectives_domains-JoopsModel.json
. Their server would consequently look for the resource joopringelberg_perspect_perspectives_domains-JoopsModel.json
in the database models_joopringelberg_perspectives_domains
.
While perfectly usable, I’d have to rename my model if I wanted to move it to a different provider, because I’d have tied my namespace to theirs (it is a subspace of theirs). That would be very impractical.
It so happens that I own the domain name joopringelberg.nl
. Suppose I created a model named model://joopringelberg.nl/JoopsModel
(notice the .nl part!), the PDR would map it to:
My server does not host a Couchdb. However, I could redirect (See Cross Origin Resource Sharing: the domain joopringelberg.nl must be indicated by the server to be allowed for CORS) that to:
The perspectives.domains server would then request the resource joopringelberg_nl-JoopsModel.json from the database models_joopringelberg_nl
. All is well!
Can I have subspaces in my namespace? Yes:
model://professional.joopringelberg.nl/JoopsModel
maps to
and is forwarded to:
and leads the server to request the resource professional_joopringelberg_nl-JoopsModel.json from the database models_professional_joopringelberg_nl/joopringelberg/nl. Again, all is well.
The takeaway is that I could identify my models like this: model://joopringelberg.nl/JoopsModel
. Identifiers like this would remain valid as long as I own the joopringelberg.nl
domain, while I could switch storage providers at will.
8.2.3.4. Model versions
We want to introduce model versioning in Perspectives using semantic versioning. Version numbers defined according to this scheme are: MAJOR.MINOR.PATCH, where each of the three parts are non-negative integers, and MUST NOT contain leading zeroes..
Version numbers will be appended to model identifiers in such a way that
-
They are accepted as part of the segment-nz-nc;
-
They are accepted as part of couchdb document names.
The semantic version number as such (consisting of numbers and “.”) can be part of both. The “@” character can be, too, so we extend our definition of the model scheme to the following production:
Identifier = “//” reg-name “/” segment-nz-nc “@” version core version core = numeric_identifier "." numeric_identifier "." <numeric identifier>
(see semantic versioning for the production of <numeric identifier>).
The versioned version of the System model:
model://perspectives.domains#System
would be, for example:
model://perspectives.domains#System@1.0.0
and be mapped to the url
while the server would map this to the document perspectives_domains-System@1.0.0
in the database models_perspectives_domains.
8.2.3.5. Pre-release versions
An author needs to maintain her model and this involves creating versions that are not accessible to the public. Yet, with the mapping from model identifier to storage location, we seem to have precluded this practice.
In order to restore it, we extend the semantic version with pre-release information. In short, we require model storage providers to use that information in the mapping of URLs to databases. See Mapping Model Identifiers to Storage Locations for details.
As a result, the identifier under the model scheme becomes:
Identifier = “//” reg-name “/” segment-nz-nc “@” version core [ - <pre-release>]
An optional pre-release string may be appended to the model name, separated from it by a hyphen.
Note
|
pre-release model version mapping to separate databases has not yet been implemented. |