Skip to end of metadata
Go to start of metadata
This page describes the COI Resource Registry. Please also check Resource and Object Model for context and see all child pages.

Overview

The COI Resource Registry provides services to describes resources under OOI governance as introduced here. Capabilities include:

  • Identifying resources uniquely in the system
  • Defining types of resources
  • Relating types of resources, such as to create inheritance trees or versions of type definitions
  • Defining the structure of resource descriptions
  • Persisting resource descriptions flexibly and efficiently
  • Cross referencing resources
  • Enabling flexible search and query of resources
  • Managing the life cycle of resources uniformly with extensibility for specific types of resources

The figure below illustrates how resources are kept in the resource registry. Every resource in the system has a unique identifier. Resources have current state. The underlying datastore maintains previous revisions of the resource objects. Associations are used to reference resources by unique ID. It is either possible to reference the head revision of a resource or a specific revision of a resource.

Figure 1. Illustration of Resource Registry Concepts (OV-1)

List of Resources

For a list of OOI Integrated Observatory resources, managed by COI Resource Registry services, see the CIAD APP Resource Model and the CIAD OV Resource and Object Model.

Concepts

Resource Identifiers

Resource identifiers (IDs) are uniquely identifying a resource instance in the system.

ID Representation

In R2 LCA, resource IDs are uuid4 strings, hex encoded, with lowercase letters and no additional separators.

The goal is to have resource identifiers that are

  • unique: every resource instance has a different resource identifier
  • unambigous: there are no 2 identifiers or identifier representations for the same resource instance
  • interoperable: generation and use of IDs is not specific to a certain platform or technology (e.g. Mac, Linux, Python, JavaScript, Java)
  • indicate the type of resource: ID verification should be possible by type without a registry lookup
  • indicate the instance of the system: ID verification should be possible by type without a registry lookup
  • can be looked up by URL: a user can use the resource ID as a valid URL in a browser

Example:

Associations

See here for an overview.

Associations are first class information objects in the system that reference 2 resources. Associations belong to neither of the two resources they associate and can be managed (i.e. defined, created, owned, manipulated and deleted) independently.

Associations provide the following information:

  • A subject resource. The resource from which the association logically originates from
  • An object resource. The resource to which the association logically points at
  • A predicate. A verb determining the interpretation of the association, e.g. "hasModel" or "ownedBy"
  • Additional association metadata, including creation timestamp, keywords and ordinal

Associations are immutable once created. They can be retired if no longer needed, leaving the association intact, but rendering it invisible for all user purposes of the system.

Associations follow a schema definition. The system will only create permissible associations. The schema defines:

  • Permissible types of subject resources for a predicate. Base types can be used, enabling the association for all specializations of this base type.
  • Permissible types of object resources for a predicate. Base types can be used, enabling the association for all specializations of this base type.
  • Multiplicity of associations for a predicate, e.g. 1:1, 1:n, n:1, n:n etc.

See also:

Resource Visibility

Every resource has one of the visibility levels listed in the table below. Visibility affects which actors can find a resource by metadata or association through the resource registry or higher level services such as discovery. System superusers (ION_MANAGER role and system actors can always see all resources, independent of the visibility level.

Level name Level code Description
PUBLIC 1 The resource is visible to any actor in the system, including anonymous (unregistered or not signed in) users
REGISTERED 2 The resource is visible to any registered and signed in actor
FACILITY 3 The resource is visible to all actors that are member in at lease one facility (Org) that the resource is shared in
OWNER 4 The resource is visible to the actor that owns the resource (and to superusers)

Resource Lifecycle

See here for overview respectively details:

Decomposition

Resources can be manipulated directly through the Capability Container's resource registry datastore interface.

Services that operate on resources remotely, and provide higher level functions include:

  • The CIAD COI OV Resource Registry Service provides a service API for the resource registry, accessible remotely, where no direct connection to the resource registry datastore exists or is not permissible.
  • The CIAD COI OV Resource Management Service provides higher level functions to operate on resources, such as the capabilities to define new resource types, or new resource type lifecycle workflows. This service also provides generic interfaces to manipulate resources of any type, without knowing details about their type. In particular, it provides an agent interface on any kind of resource.

Implementation Details

Extended and Computed Resource Attributes

A resource represents a physical or electronic entity within the system. This entity is characterized by metadata. Other information can be computed about a resource. Metadata is persisted in the datastore, computed attributes are evaluated and set when a resource is read by a specific service. Both persisted and computed attributes are represented as attributes in the resource specification.

Computed attributes will be calculated by the service responsible for the underlying associated resource, for example, the Instrument Management Service is responsible for managing the InstrumentDevice persisted resource, so therefore the associated calculated attributes would be fulfilled by the same service but the underlying resource framework will handle the mechanics. The set of computed attributes are defined in a standard YAML object and must extend from the object ComputedAttributes and will be associated to the underlying resource using an extended resource object defined in YAML which must extend from the ResourceContainer object. Both objects utilize decorators within the YAML definition which specify how the values are determined, either from a method or based off an association specified in the YAML as well.

The base ResourceContainer object contains the fields resource and computed which will be set to the underlying resource object and specific computed attribute object, respectively.

The following illustrates the fields which are common to all extended resources which are considered ExtendedInformationResource or ExtendedTaskableResource objects.

The following is an example of a computed attribute object:

The following is an example of an extended resource object used to contain the persisted resource, the computed attributes and can also include other extended attributes based on associations or other information provided by the service.

The service will use the underlying ExtendedResourceContainer class which is available in the container which has a single factory type method:

which returns the extended resource object containing the underlying persisted resource and optional computed attributes as well as any other extensions specified in the yaml files.

And a comparable version for submitting a list of IDs of the same extended resource type, which returns a list of the resultant extended resources:

The Extended Resource framework supports the following yaml decorators:

Decorator
Description
Examples
hasABC
This decorator is used to set the value of a field to a list of objects, a single object or the count of associations, depending on the default value of the field; a list, resource object or int, respectively. This decorator requires a valid association to be specified.

If this decorator is a compound association, meaning a set of associations, then one or two filters can be specified which will be used to limit the number of associations to the ones that match the specified types.
#@hasResource
#@hasResource=InstrumentModel
#@hasAgentForDevice=InstrumentModel,InstrumentAgent
Method
This decorator is used to set the value of a field to the value of a function, which must be implemented by the resource framework or the service calling the resource framework. If the name of the method is not specified as a name/value pair then the name of the function will be the name of the field appended to "get_"; for example, get_software_version.  A method name using dot notation implies a remote method call using messaging.
#@Method
#@Method=get_data_url
#@Method=user_notification.get_subscription

All methods specified in the YAML code should be prepared to take a resource id as a parameter for the underlying reference and must return the value as specified in the yaml file. For example:

YAML Definition
Code
Notes
#@Method
  location: !GeospatialBounds
def get_location(self, resource_id):
        return IonObject(OT.GeospatialBounds)
This version requires that the local method must be named the same as the field name.
#@Method=get_data_url
  data_produced: ""   # the URL of the data location
def get_data_url(self,resource_id):
        return "http://iontest/data/" + instrument_device_id
This version allows local method can be named differently than the field name.
#@Method=user_notification.get_subscription
  user_subscriptions: []   # Users subscribed to this resource
def get_subscription(self,resource_id, user_id):
        ...
        return []
This version means the method is not local to the process but will use messaging to make the request to the remote method. It uses the standard <process name>.<method name>
#@hasAgentInstance
  instrument_agent: !InstrumentAgentInstance 
#@hasAgentInstance 
  instrument_agent: 
N/A - handled by framework - sets the field to the first associated object found or to None if no associated object found

This should only be used for 1:1 or 1:0..1 associations. For 1..n associations it non-deterministically chooses one of the associated resources and ignores the rest (a warning will be logged). In most cases this is not anticipated

Order in which the associations are processed:
  1. If this predicate is defined for the specific resource type in object direction, finds associations in object direction
    1. If resources in object direction found, sets them (the first in this case)
    2. Only if no resources found in object direction, finds associations in subject direction (WARNING: this is ambiguous if the resource has the same predicate in both directions, e.g. hasSite)
  2. If this predicate is defined for the specific resource type in subject direction, finds associations in subject direction only
  3. If this predicate is defined for a base type in object direction, finds associations in object direction
    1. If resources in object direction found, sets them (the first in this case)
    2. Only if no resources found in object direction, finds associations in subject direction (WARNING: this is ambiguous if the resource has the same predicate in both directions, e.g. hasSite)
  4. If this predicate is defined for a base type in subject direction, finds associations in subject direction
#@hasPolicy
  policies: []  # A list of policies associated with the underlying resource
N/A - handled by framework - sets the field to the list of associated objects.  
#@hasPolicy
  policy_count: 0  # The number of associated policies
N/A - handled by framework - sets the field to the count of associated objects.  
#@hasSite=PlatformSite,InstrumentSite
  site: !Site
N/A - handled by framework - sets the field to the first associated object found that is of type PlatformSite or InstrumentSite
One or more specific resource types can be listed here. These must be the actual types of associated resources, not base types.
#@hasSite> 
  child_sites: []
#@hasSite<
  parent_site: !Site
N/A - handled by framework - sets the field to the first associated object found when traversing associations in object/child direction (">") or subject/parent direction ("<") Can be combined with types

Method Parameters

Any methods returning data as Computed Attributes must have a signature where the first parameter is the id of the specified resource. Additional parameters can be passed to computed methods, but they must follow the first parameter:  for example:

The extended resource framework will pass the resource_id of the requested resource as the first parameter to any computed method and all subsequent parameters must be passed in as name=value pairs  as the trailing parameters to the create_extended_resource_container() method call as the last parameter(s). An example is as follows:

Labels

read-coi read-coi Delete
read-dm read-dm Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.