Repository Open Service Interface Definitions repository version 3.0.0

The Repository OSID provides the service of finding and managing digital assets.

Assets

An Asset represents a unit of content, whether it be an image, a video, an application document or some text. The Asset defines a core set of definitions applicable to digital content, such as copyright and publisher, and allows for a type specification to be appended as with other OsidObjects.

Asset content, such as a document, is defined such that there may be multiple formats contained with the same asset. A document may be accessible in both PDF and MS Word, but is the same document, for example. An image may have both a large size and a thumbnail version. Generally, an asset contains more than one version of content when it is left to the application to decide which is most appropriate.

The Asset Type may define methods in common throughout the content variations. An example asset is one whose content Types are “Quicktime” and “MPEG”, but the Asset Type is “movie” and defines methods that describe the move aside from the formats. This “double” Type hierarchy stemming from the asset requires more care in defining interfaces.

Assets also have “credits” which define the authors, editors, creators, performers, producers or any other “role”, identified with a role Type, with the production of the asset. These are managed externally to the asset through another OsidSession.

Through additional optional OsidSessions, the Asset can be “extended” to offer temporal information. An asset may pertain to a date, a period of time, or a series of dates and periods. This mechanism is to offer the ability to search for assets pertaining to a desired date range without requiring understanding of a Type.

Similarly, the Asset can also map to spatial information. A photograph may be “geotagged” with the GPS coordinates where it was taken, a conical shape in stellar coordinates could be described for an astronimocal image, or there may be a desire to may a historical book to the spatial coordinates of Boston and Philadelphia. Unlike temporal mappings, the definition of the spatial coordinate is left to a spatial Type to define. The Repository OSID simply manages spatial mappings to the Asset.

Asset Tagging

Assets may also relate to Ontology OSID Subjects. The Subject provides the ability to normalize information related to subject matter across the Assets to simplify management and provide a more robust searching mechanism. For example, with a photograph of the Empire State Building, one may wish to describe that it was designed by Shreve, Lamb and Harmon and completed in 1931. The information about the building itself can be described using a Subject and related to the photograph, and any other photograph that captures the building. The Asset Type for the photograph may simply be “photograph” and doesn’t attempt to describe a building, while the AssetContent Type is “image/jpeg”.

An application performing a search for Empire State Building can be execute the search over the Subjects, and once the user has narrowed the subject area, then the related Assets can be retrieved, and from there negotiate the content.

A provider wishing to construct a simple inventory database of buildings in New York may decide to do so using the Resource OSID. The Resource Type may describe the construction dates, height, location, style and architects of buildings. The Type may also include a means of getting a reference image using the Asset interface. Since there is no explicit relationship between Subject and Resource, the Resource can be adapted to the Subject interface (mapping a building_resource_type to a building_subject_type ) to use the same data for Subject to Asset mappings and searching.

Asset Compositions

Asset compositions can be created using the Composition interface. A Composition is a group of Assets and compositions may be structured into a hierarchy for the purpose of “building” larger content. A content management system may make use of this interface to construct a web page. The Composition hierarchy may map into an XHTML structure and each Asset represent an image or a link in the document. However, the produced web page at a given URL may be represented by another single Asset that whose content has both the URL and the XHTML stream.

Another example is an IMS Common Cartridge. The Composition may be used to produce the zip file cartridge, but consumers may access the zip file via an Asset .

Repository Cataloging

Finally, Assets and Compositions may be categorized into Repository objects. A Repository is a catalog-like interface to help organize assets and subject matter. Repositories may be organized into hierarchies for organization or federation purposes.

This number of service aspects to this Repository OSID produce a large number of definitions. It is recommended to use the RepositoryManager definition to select a single OsidSession of interest, and work that definition through its dependencies before tackling another aspect.

Sub Packages

The Repository OSID includes a rules subpackage for managing dynamic compositions.

Service Managers

Repository Manager

class dlkit.services.repository.RepositoryManager

Bases: dlkit.osid.managers.OsidManager, dlkit.osid.sessions.OsidSession, dlkit.services.repository.RepositoryProfile

repository_batch_manager

Gets a RepositoryBatchManager.

Returns:a RepostoryBatchManager Return type:osid.repository.batch.RepositoryBatchManager Raise:OperationFailed – unable to complete request Raise:Unimplemented – supports_repository_batch() is false

repository_rules_manager

Gets a RepositoryRulesManager.

Returns:a RepostoryRulesManager Return type:osid.repository.rules.RepositoryRulesManager Raise:OperationFailed – unable to complete request Raise:Unimplemented – supports_repository_rules() is false

Repository Profile Methods

RepositoryManager.supports_asset_lookup()

Tests if asset lookup is supported.

Returns:true if asset lookup is supported , false otherwise Return type:boolean

RepositoryManager.supports_asset_query()

Tests if asset query is supported.

Returns:true if asset query is supported , false otherwise Return type:boolean

RepositoryManager.supports_asset_admin()

Tests if asset administration is supported.

Returns:true if asset administration is supported, false otherwise Return type:boolean

RepositoryManager.supports_repository_lookup()

Tests if repository lookup is supported.

Returns:true if repository lookup is supported , false otherwise Return type:boolean

RepositoryManager.supports_repository_admin()

Tests if repository administration is supported.

Returns:true if repository administration is supported, false otherwise Return type:boolean

RepositoryManager.asset_record_types

Gets all the asset record types supported.

Returns:the list of supported asset record types Return type:osid.type.TypeList

RepositoryManager.asset_search_record_types

Gets all the asset search record types supported.

Returns:the list of supported asset search record types Return type:osid.type.TypeList

RepositoryManager.asset_content_record_types

Gets all the asset content record types supported.

Returns:the list of supported asset content record types Return type:osid.type.TypeList

RepositoryManager.composition_record_types

Gets all the composition record types supported.

Returns:the list of supported composition record types Return type:osid.type.TypeList

RepositoryManager.composition_search_record_types

Gets all the composition search record types supported.

Returns:the list of supported composition search record types Return type:osid.type.TypeList

RepositoryManager.repository_record_types

Gets all the repository record types supported.

Returns:the list of supported repository record types Return type:osid.type.TypeList

RepositoryManager.repository_search_record_types

Gets all the repository search record types supported.

Returns:the list of supported repository search record types Return type:osid.type.TypeList

RepositoryManager.spatial_unit_record_types

Gets all the spatial unit record types supported.

Returns:the list of supported spatial unit record types Return type:osid.type.TypeList

RepositoryManager.coordinate_types

Gets all the coordinate types supported.

Returns:the list of supported coordinate types Return type:osid.type.TypeList

Repository Lookup Methods

RepositoryManager.can_lookup_repositories()

Tests if this user can perform Repository lookups. A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a PermissionDenied. This is intended as a hint to an application that may opt not to offer lookup operations to unauthorized users.

Returns:false if lookup methods are not authorized, true otherwise Return type:boolean

RepositoryManager.use_comparative_repository_view()

The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error. This view is used when greater interoperability is desired at the expense of precision.

RepositoryManager.use_plenary_repository_view()

A complete view of the Repository returns is desired. Methods will return what is requested or result in an error. This view is used when greater precision is desired at the expense of interoperability.

RepositoryManager.get_repositories_by_ids(repository_ids)

Gets a RepositoryList corresponding to the given IdList. In plenary mode, the returned list contains all of the repositories specified in the Id list, in the order of the list, including duplicates, or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible Repositories may be omitted from the list and may present the elements in any order including returning a unique set.

Parameters:repository_ids (osid.id.IdList) – the list of Ids to retrieve Returns:the returned Repository list Return type:osid.repository.RepositoryList Raise:NotFound – an Id was not found Raise:NullArgument – repository_ids is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

RepositoryManager.get_repositories_by_genus_type(repository_genus_type)

Gets a RepositoryList corresponding to the given repository genus Type which does not include repositories of types derived from the specified Type. In plenary mode, the returned list contains all known repositories or an error results. Otherwise, the returned list may contain only those repositories that are accessible through this session.

Parameters:repository_genus_type (osid.type.Type) – a repository genus type Returns:the returned Repository list Return type:osid.repository.RepositoryList Raise:NullArgument – repository_genus_type is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

RepositoryManager.get_repositories_by_parent_genus_type(repository_genus_type)

Gets a RepositoryList corresponding to the given repository genus Type and include any additional repositories with genus types derived from the specified Type. In plenary mode, the returned list contains all known repositories or an error results. Otherwise, the returned list may contain only those repositories that are accessible through this session.

Parameters:repository_genus_type (osid.type.Type) – a repository genus type Returns:the returned Repository list Return type:osid.repository.RepositoryList Raise:NullArgument – repository_genus_type is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

RepositoryManager.get_repositories_by_record_type(repository_record_type)

Gets a RepositoryList containing the given repository record Type. In plenary mode, the returned list contains all known repositories or an error results. Otherwise, the returned list may contain only those repositories that are accessible through this session.

Parameters:repository_record_type (osid.type.Type) – a repository record type Returns:the returned Repository list Return type:osid.repository.RepositoryList Raise:NullArgument – repository_record_type is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

RepositoryManager.get_repositories_by_provider(resource_id)

Gets a RepositoryList from the given provider ````. In plenary mode, the returned list contains all known repositories or an error results. Otherwise, the returned list may contain only those repositories that are accessible through this session.

Parameters:resource_id (osid.id.Id) – a resource Id Returns:the returned Repository list Return type:osid.repository.RepositoryList Raise:NullArgument – resource_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

RepositoryManager.repositories

Gets all Repositories. In plenary mode, the returned list contains all known repositories or an error results. Otherwise, the returned list may contain only those repositories that are accessible through this session.

Returns:a list of Repositories Return type:osid.repository.RepositoryList Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

Repository Admin Methods

RepositoryManager.can_create_repositories()

Tests if this user can create Repositories. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a Repository will result in a PermissionDenied. This is intended as a hint to an application that may not wish to offer create operations to unauthorized users.

Returns:false if Repository creation is not authorized, true otherwise Return type:boolean

RepositoryManager.can_create_repository_with_record_types(repository_record_types)

Tests if this user can create a single Repository using the desired record types. While RepositoryManager.getRepositoryRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific Repository. Providing an empty array tests if a Repository can be created with no records.

Parameters:repository_record_types (osid.type.Type[]) – array of repository record types Returns:true if Repository creation using the specified Types is supported, false otherwise Return type:boolean Raise:NullArgument – repository_record_types is null

RepositoryManager.get_repository_form_for_create(repository_record_types)

Gets the repository form for creating new repositories. A new form should be requested for each create transaction.

Parameters:repository_record_types (osid.type.Type[]) – array of repository record types Returns:the repository form Return type:osid.repository.RepositoryForm Raise:NullArgument – repository_record_types is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure Raise:Unsupported – unable to get form for requested record types

RepositoryManager.create_repository(repository_form)

Creates a new Repository.

Parameters:repository_form (osid.repository.RepositoryForm) – the form for this Repository Returns:the new Repository Return type:osid.repository.Repository Raise:IllegalState – repository_form already used in a create transaction Raise:InvalidArgument – one or more of the form elements is invalid Raise:NullArgument – repository_form is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure Raise:Unsupported – repository_form did not originate from get_repository_form_for_create()

RepositoryManager.can_update_repositories()

Tests if this user can update Repositories. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a Repository will result in a PermissionDenied. This is intended as a hint to an application that may not wish to offer update operations to unauthorized users.

Returns:false if Repository modification is not authorized, true otherwise Return type:boolean

RepositoryManager.get_repository_form_for_update(repository_id)

Gets the repository form for updating an existing repository. A new repository form should be requested for each update transaction.

Parameters:repository_id (osid.id.Id) – the Id of the Repository Returns:the repository form Return type:osid.repository.RepositoryForm Raise:NotFound – repository_id is not found Raise:NullArgument – repository_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

RepositoryManager.update_repository(repository_form)

Updates an existing repository.

Parameters:repository_form (osid.repository.RepositoryForm) – the form containing the elements to be updated Raise:IllegalState – repository_form already used in an update transaction Raise:InvalidArgument – the form contains an invalid value Raise:NullArgument – repository_form is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure Raise:Unsupported – repository_form did not originate from get_repository_form_for_update()

RepositoryManager.can_delete_repositories()

Tests if this user can delete Repositories. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a Repository will result in a PermissionDenied. This is intended as a hint to an application that may not wish to offer delete operations to unauthorized users.

Returns:false if Repository deletion is not authorized, true otherwise Return type:boolean

RepositoryManager.delete_repository(repository_id)

Deletes a Repository.

Parameters:repository_id (osid.id.Id) – the Id of the Repository to remove Raise:NotFound – repository_id not found Raise:NullArgument – repository_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

RepositoryManager.can_manage_repository_aliases()

Tests if this user can manage Id aliases for repositories. A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a PermissionDenied. This is intended as a hint to an application that may opt not to offer alias operations to an unauthorized user.

Returns:false if Repository aliasing is not authorized, true otherwise Return type:boolean

RepositoryManager.alias_repository(repository_id, alias_id)

Adds an Id to a Repository for the purpose of creating compatibility. The primary Id of the Repository is determined by the provider. The new Id is an alias to the primary Id. If the alias is a pointer to another repository, it is reassigned to the given repository Id.

Parameters:

• repository_id (osid.id.Id) – the Id of a Repository
• alias_id (osid.id.Id) – the alias Id

Raise:

AlreadyExists – alias_id is in use as a primary Id

Raise:

NotFound – repository_id not found

Raise:

NullArgument – repository_id or alias_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure