agent-media-type.md

RMap Agent Media Type

This document describes the media type for version 1.0 of the RMap Agent.

• General Description
• Media Type
• Required Namespaces
• Elements
• Example Agents
• RMap API Usage of this Media Type

General Description

An RMap Agent represents a person or system that creates RMap DiSCOs. Each DiSCO is tied to an Agent via its rmap:Event information. If the User signed up using the Google, Twitter, or ORCID login on the public GUI, the Agent will be associated with that login. The Agent object is created the first time a client uses the key/secret credentials to create a DiSCO. Unlike DiSCO records, which are immutable, Agents have a persistent URI but can change over time. These changes are recorded by persistent, immutable Event graphs.

Media Type

type	application
Subtype	vnd.rmap-project.agent+rdf+turtle vnd.rmap-project.agent+rdf+ld+json vnd.rmap-project.agent+rdf+xml
Parameters	version

Example media type

To specify a specific version of the media representation in the GET request header:

Accept: application/vnd.rmap-project.agent+rdf+xml;version=1.0

Required Namespaces

The following namespaces are used in the Agent model

Namespace	URI	Description
rdf *	http://www.w3.org/1999/02/22-rdf-syntax-ns#	Resource Description Framework. RDF/XML.
rmap *	http://purl.org/ontology/rmap#	Vocabulary to describe resources in RMap.
foaf *	http://xmlns.com/foaf/0.1/	Friend-of-a-friend vocabulary. FOAF.

* Used in all Agents for required fields

Elements

Element Name	Occurrence	Description
rdf:type	1	Required. Will always be rmap:Agent
foaf:name	1	Required. Is the name associated with the Agent, as provided by the user that created it.
rmap:identityProvider	1 or more	At least one required. Indicates which identify provider (Google, Twitter, ORCID, or the rmap:Administrator) was used to authorize the creation of the Agent account
rmap:userAuthId	1 or more	At least one required. Auto-generated by RMap GUI. Represents a combination of the identity provider and user name converted to SHA256 and appended to the RMap Project prefix. This will support validation of identities by end users.

Example Agents

application/rdf+xml

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:rmap="http://purl.org/ontology/rmap#"
    xmlns:dcterms="http://purl.org/dc/terms/"
    xmlns:foaf="http://xmlns.com/foaf/0.1/">
     
    <rdf:Description rdf:about="ark:/22573/rmd227j">     <!-- internal rmap:Agent URI --> 
        <rdf:type rdf:resource="http://purl.org/ontology/rmap#Agent"/>
        <foaf:name>Josiah S. Carberry</foaf:name>
        <rmap:identityProvider rdf:resource="http://orcid.org"/>
        <rmap:userAuthId rdf:resource="rmap:/authid/kajdf3942..."/>
    </rdf:Description>
</rdf:RDF>

text/turtle

@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rmap: <http://purl.org/ontology/rmap#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
 
<ark:/22573/rm227j>
 a rmap:Agent ;
 foaf:name “John Smith”
 rmap:identityProvider <http://orcid.org/> ;
 rmap:userAuthId <rmap:/authid/kajdf3942ja5jsdkflj2ask> .

RMap API Usage of this Media Type

See the full API documentation for a detailed description of each API operation.

Example API Interactions

Retrieve Agent Request (GET)

Note: generic accept type application/rdf+xml will create the same response.

GET https://test.map-hub.org/agents/ark%3A%2F00000%2Fdf8wekijfdsl HTTP/1.1
Accept: application/vnd.rmap-project.agent+rdf+xml

Successful Retrieve Agent Response

HTTP/1.1 200 OK
Date: Tue, 18 Nov 2014 11:11:12 GMT
Content-length: nnn
Content-type: application/vnd.rmap-project.agent+rdf+xml; version=1.0
Location: http://test.rmap-hub.org/api/agents/ark%3A%2F00000%2Fdf8wekijfdsl
Link: <http://purl.org/ontology/rmap#active>;
            rel=“http://purl.org/ontology/rmap#hasStatus”
 
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:rmap="http://purl.org/ontology/rmap#"
    xmlns:dcterms="http://purl.org/dc/terms/"
    xmlns:foaf="http://xmlns.com/foaf/0.1/">
     
    <rdf:Description rdf:about="ark:/00000/df8wekijfdsl">    
        <rdf:type rdf:resource="http://purl.org/ontology/rmap#Agent"/>
        <foaf:name>Josiah S. Carberry</foaf:name>
        <rmap:identityProvider rdf:resource="https://orcid.org"/>
        <rmap:userAuthId rdf:resource="rmap:/authid/2f80298b5e2ef...8e2e45d739e10"/>
    </rdf:Description>
</rdf:RDF>