Object model
Object Model
The following diagram depicts the all of the objects you can manage and interact with using REST. All objects are RDF resources. You can think of them as RDF documents which, once created, are identified by a URI. You can create, update, read, and delete these objects by issuing HTTP requests to the URI of the resource or its parent container (e.g. POST, PUT, GET, DELETE). There are also other types of RESTful operations that each object might expose depending on the type of the object. The object hierarchy depicts how certain objects extend others and thus would have the same RESTful operations or behavior as the parent type.
Object Descriptions
Following is a brief description for each of the objects, listed in alphabetical order.
AccessPoint
An AccessPoint is a class of container that can manage member resources stored in another container other than itself. Both DirectContainer and IndirectContainer are of this class. However, since the IndirectContainer is not yet implemented in Carbon, the AccessPoint can be regarded as equivalent to DirectContainer. An AccessPoint is useful when you want to manage more than one list of members for more than one given property on a resource. To understand how this is useful, consider the BasicContainer in contrast. A BasicContainer stores its members in itself, but is limited to managing only one list of members by one single property (e.g. ex:hasChildren
). If you need multiple membership properties on a container, each managing a kind of membership to the resource (and where the members may not exist within the container itself), the AccessPoint can help. Imagine a BlogPost resource, for example. With an AccessPoint, you could define properties like ex:comment
, ex:tag
, ex:like
all on the same BlogPost resource with each property managing one or more members. The comments or tag resources may be stored in child comments and tags containers, but they are managed and enumerated by the parent BlogPost container.
AccessControlList
A configuration resource that defines the security access control for a given resource. An AccessControlList controls access to a resource by defining what permissions one or more given roles have on the resource. The ACL defines an accessControlEntry
and an inheritableEntry
– each linking to an AccessControlEntry
by way of a blank nodes. The entry linked by accessControlEntry
defines access to the resource itself. The entry linked by inheritableEntry
defines permissions that can be inherited by child resources when the child resources do not override them.
Agent
An RDFSource document that represents a user or system account that can authenticate with the Carbon platform or a Carbon application.
Application
An RDSource document that represents an application in the Carbon platform. In order to create a new Carbon application, you must post an Application RDFSource document. Doing so creates the root container for your new application, under which you can begin posting application-specific resources.
AppRole
An RDFSource document that is used to control access to application resources. An AppRole defines what kind of access a group of agents have on one or more resources. An AppRole is defined by the rdf:type
of https://carbonldp.com/ns/v1/security#AppRole
(or cs:AppRole
, for short).
Backup
An RDFRepresentation that describes the zip archive created by an ExportBackup job; it contains information such as the archive’s format, size, and cretaion time, for example.
BasicContainer
An LDP Container whose members are stored within itself. In a BasicContainer, the property ldp:contains
defines a set of triples, maintained by the container, which are documents created by the container. In LDP terminology, these are called “containment triples” and they always bear the triple form of: <Container URI> <ldp:contains> <Document URI>
Basic Containers provide the most straight-forward way to have generic storage in Carbon and for creating a containment hierarchy of arbitrary resources.
Container
As the name implies, LDP Containers contains things. They don’t actually literally contain resources, but rather – they contain links pointing to other resources. Basically, they represent collections. A container responds to client requests for creation, modification, and/or enumeration of its linked members. In other words, the URI that identifies a given container acts as an HTTP interaction point through which members and membership can be managed. A container is also an RDFSource, so while it has a special function as a membership controller, it may also represent additional data that is valuable to the clients that access it. In other words, you can interact with a Container as both a membership controller and as an RDFSource document. The behavior depends upon the interaction model defined as part of your request. There are three different types of LDP containers, each with variant uses and capabilities, and described by one of the three container types with rdf:type
of ldp:BasicContainer
, ldp:DirectContainer
, or ldp:IndirectContainer
. See also: Linked Data Platform Containers [LDP]
DirectContainer
See AccessPoint
Execution
A resource that represents the execution of a Job and contains information about the job’s execution such as the start time, end time, state of the job’s execution, and, for certain types of jobs, where the results of the job execution are stored.
ExportBackupJob
A type of Job that, when executed, will export the data of a Carbon application for backup purposes or for importing into another server. When an ExportBackup job is executed, it creates a zip archive file inside of which can be found a *.trig
file that has all the application data (e.g. triples), and a folder containing all of the application’s NonRDFSource resources such as images and files. The archive produced by an ExportBackup can be subsequently imported with an ImportBackup job.
ImportBackupJob
A type of Job that, when executed, will replace a Carbon application’s resources with the resources created by an ExportBackup job.
ImportLDAPAgentsJob
A type of Job that, when executed, creates LDAPAgents that contain properties that can be used as credentials for authentication. This Job can be configured so only certain user properties are copied from the LDAP server when the representative LDAPAgent is created.
IndirectContainer
Though defined in the W3C Linked Data Platform 1.0 specification [LDP], IndirectContainers are not yet supported by Carbon.
Job
A Job is a resource that defines one or more specialized tasks to be executed on the server. A Job may be scheduled or configured to run on demand. Each time the job runs, an Execution document is created with information about the job’s execution.
LDAPAgent
A special type of Agent that is created based on the information retrieved from an LDAP server when an ImportLDAPAgentsJob is executed.
LDAPServer
An LDP RDFSource that contains the required configuration information to connect to an LDAP server.
RDFRepresentation
An RDFRepresentation is an RDFSource that contains meta-data (properties) about a Non-RDFSource (a file or binary). When a file is uploaded into a Carbon app or otherwise created by Carbon, the RDFRepresentation is also created to describe and store various information about the file.
RDFSource
A resource (basically, a document in Carbon) whose state is fully represented in RDF. An RDFSource is identified by a URI, which can be used with HTTP requests (GET, PUT, POST, DELETE). The content of an RDFSource document is an RDF graph – a set of RDF triples. The triples are the data properties of the resource, which can be either literal properties (string, date, number, etc.) or object properties (links to other resource URIs). All resources you create within a Carbon application, with the exception of ACLs, are RDFSource documents. That is to say, they are described by the rdf:type
of http://www.w3.org/ns/ldp#RDFSource
, even if also described by additional types such as those that define the object classes of your application.
See also:
- Linked Data Platform Resources [LDP]
- RDF Source [LDP]
References
Steve Speicher; John Arwe; Ashok Malhotra. W3C. Linked Data Platform 1.0. 26 February 2015. W3C Recommendation. URL: http://www.w3.org/TR/ldp/