Introduction

Welcome to the CloudObjects Core Documentation! The objective of this documentation is to introduce the object repository and distribution functionality. It is not required to read and know all the details in this document if you intend to use CloudObjects only as a developer account and interact with developer products built on CloudObjects through their higher level interfaces. This document is targeted at developers who want to leverage the full functionality of CloudObjects through the CLI or API or simply want to know what's going on "under the hood".

Object Identifiers

The unique identifier for any object stored in CloudObjects is a URI (Uniform Resource Identifier) starting with coid://, followed by a valid DNS hostname (e.g. example.com), and optionally one or two segments, separated by slashes (/). All objects with the same hostname make up a namespace. Identifiers are also called COIDs (CloudObject Identifiers) and are grouped into the following types:

Root COID

An identifier containing only the hostname which identifies the namespace itself (the "root object").
Example: coid://example.com

Non-Versioned COID

An identifier with a single segment after the slash which contains the unique name of a object in the namespace.
Example: coid://example.com/SampleObject

Versioned COID

An identifier containing two segments in which the first segment contains the name of a object in the namespace and the second segment contains the version of this object.
Example: coid://example.com/SampleVersionedObject/1.0

COIDs are case-sensitive and may only include A-Z, a-z, -, _, . and 0-9. The domain is always lower-case. The name segment should be properly capitalized if it is a noun (most objects are) and use camel-case for concatenating words, however this is just a convention and not enforced.

Developers should verify control of a hostname before creating objects in its namespace.

Object Description

The description of an object in CloudObjects is based on RDF (Resource Description Framework). If you are unfamiliar with RDF, the gist of what you need to know is that RDF describes objects with triples; basically these are key-value pairs that belong to a subject resource (e.g. a CloudObjects object), in which the key (= predicate) is a URI to avoid namespace collisions and the value can either by a (typed) literal or another resource/object identified by a URI.

An object can have one or more types. Each type declaration is an RDF triple with rdf:type as the predicate and a class as the value. While RDF supports resources without types, objects in CloudObjects require at least one type. Classes are also objects - either stored in CloudObjects or in an external RDF ontology - and they can have subclasses.

The object identified by the Root COID needs to have the co:Namespace type or any of its subclasses.

Visibility and Access Control

CloudObjects provides a sophisticated permission and access control system in order to make object descriptions selectively available to the people and the other objects that require it.

Read the Permission System Documentation for more information.

Configuration Workflow

Descriptions of new or modified objects in CloudObjects are processed as configuration jobs. Jobs can be added to CloudObjects from RDF documents through the Dashboard or the CLI Tool (cloudobjects configuration-job:create or cloudobjects confjob commands). Developer products built on top of CloudObjects can provide an abstraction layer over RDF.

Any RDF input is checked for well-formedness and structural validity before a job is accepted. While processing the job, all triples are inspected and it is verified that each object referenced as predicate or value exists and all permissions and dependencies are met.

If everything is approved, a new revision of the object description is permanently stored, made available to all objects that depend on the configured object via co:ObjectAPI/1.0 and the directory.

CloudObjects also allows to store a limited number as arbitrary files as attachments to objects. This functionality is used by some developer products. The triples stored inside CloudObjects can be imported and exported in every well-known serialization of RDF for better interoperability with other RDF-based tools and products.