1. Introduction
Solid affords us the opportunity to create a valuable and powerful ecosystem where people and organizations retain control of their data, but are also able to put it to work and use it to its full potential. The fundamentals of Solid make this possible, but further definition of standard methods and mechanisms must be established to make it practical, intuitive, and secure.
Note: See Problems and Goals for Interoperability in Solid for a detailed explanation of the problem space.
This specification details how Agents in the Solid ecosystem can read, write, and manage data stored in a Solid pod using disparate Applications, either individually or in collaboration with other Agents.
§ 4 Application Registration lets Agents register and track the Applications they’ve decided to use.
§ 5 Data Registration lets Agents register, organize, and lookup their data. Data is stored uniformly, avoiding complex physical hierarchies. Shape trees and shapes provide strong data validation and intuitive data boundaries.
§ 6 Data Authorization provides the means for an Agent to grant other Agents and Applications access to data in their control.
-
§ 7 Access Needs let Agents and Applications express which data they need access to, and patterns to request those needs.
-
§ 8 Access Grants let Agents manage and track access they’ve granted to other Agents and Applications.
-
§ 9 Access Receipts are provided by Agents to other Agents and Applications to let them know about the access they’ve been granted.
-
§ 10 Remote Data Registration lets Agents maintain a local registry of remote data that has been shared with them by other Agents.
2. Agent
2.1. Overview
Agents represent the primary actors in an interoperable Solid ecosystem.
An Agent is denoted by an identity. Dereferencing that identity leads to the Agent, and a graph of useful information about them. This graph is used by the Agent to look up their own data, as well as data that has been shared with them.
An Agent is designed to be publicly accessible, but many of the things the Agent links to are designed to be private, or accessible only by other Agents or Applications that the Agent has authorized.
Consequently, other Agents and Applications can dereference the identity of an Agent to obtain the information they need to interact with them.
Most of an Agent’s information is stored in Registries. A Registry is a place where an Agent can store and find different types of data, often for particular purposes. Each type of Registry serves a specific purpose or function.
Registry | Description |
---|---|
Application Registry | Records the Applications that a given Agent uses or has given access to. See Application Registration |
Data Registry | Stores and organizes data types for interoperable use by different Applications and shared with other Agents See Data Registration |
Access Grant Registry | Records access granted to other Agents and/or Applications See Access Grants |
Access Receipt Registry | Tracks access that has been granted by other Agents See Access Receipts |
Remote Data Registry | Local references to data that has been shared by other Agents See Remote Data Registration |
2.2. Data Model
2.2.1. Summary
When an Agent has more than one pod, or is managing data on behalf of another Agent, they will be linked to multiple Registries of the same type. A Registry Set is used to organize Registries of the same type together.
An Agent links to each kind of Registry Set through type-specific subproperties of interop:hasRegistrySet.
This allows one Agent to link to many Registries across the Web, without exposing those Registries in a public document. Different permissions can be assigned to each Registry Set, depending on the sensitivity of the Registries they link to.
Registry Sets link to Registries through the interop:hasRegistry property.
2.2.2. Agent
An Agent is a distinct individual, group, organization, or piece of software with an identity that can be strongly authenticated.
Agent | ||
---|---|---|
Property | Range | Description |
hasApplicationRegistrySet | ApplicationRegistrySet | Application Registry Set for the Agent |
hasDataRegistrySet | DataRegistrySet | Data Registry Set for the Agent |
hasAccessGrantRegistrySet | AccessGrantRegistrySet | Access Grant Registry Set for the Agent |
hasAccessReceiptRegistrySet | AccessReceiptRegistrySet | Access Receipt Registry Set for the Agent |
hasRemoteDataRegistrySet | RemoteDataRegistrySet | Remote Data Registry Set for the Agent |
hasInbox | ldp:inbox | A general inbox for messages sent to the Agent |
hasAccessInbox | ldp:inbox | An inbox for access related messages sent to the Agent |
receivesAccessReceipt | interop:ReceiptInMessage, interop:ReceiptInRegistration | Identifies whether Access Receipts should be sent directly to the Application or provided in the Application Registration if the Agent is also an Application |
The AgentShape is used to validate an instance of the Agent class.
<#AgentShape> { a [ interop: Agent ] ; interop: hasApplicationRegistrySet IRI; interop: hasDataRegistrySet IRI; interop: hasAccessGrantRegistrySet IRI; interop: hasAccessReceiptRegistrySet IRI; interop: hasRemoteDataRegistrySet IRI; interop: hasInbox IRI; interop: hasAccessInbox IRI; interop: receivesAccessReceipt [ interop: ReceiptInMessage interop: ReceiptInRegistration ] }
The AgentTree is assigned to a resource to ensure it will validate against the AgentShape.
<#AgentTree> a st: ShapeTree ; st: expectsType st: ShapeTreeResource ; st: validatedBy <interops#AgentShape> .
2.3. Resource Hierarchy
Resource | Class | Shape | Shape Tree |
---|---|---|---|
/profile/
| - | - | ProfileTree |
-- id#me
| Agent | AgentShape | AgentTree |
-- application#set
| ApplicationRegistrySet | ApplicationRegistrySetShape | ApplicationRegistrySetTree |
-- data#set
| DataRegistrySet | DataRegistrySetShape | DataRegistrySetTree |
-- grant#set
| AccessGrantRegistrySet | AccessGrantRegistrySetShape | AccessGrantRegistrySetTree |
-- receipt#set
| AccessReceiptRegistrySet | AccessReceiptRegistrySetShape | AccessReceiptRegistrySetTree |
-- remote#set
| RemoteDataRegistrySet | RemoteDataRegistrySetShape | RemoteDataRegistrySetTree |
/inbox/access
| ldp:inbox | - | AccessInboxTree |
/inbox/general
| ldp:inbox | - | - |
Agent resources MAY use any resource or subject names. The names used herein have been selected for comprehension and readability.
2.4. Permission Model
The permission model for the resources detailed in § 2.3 Resource Hierarchy are illustrated in the table below.
Notable items:
-
The identity profile document
id
which contains the Agent instance gives the public read-only access. -
Registry Sets are not publicly exposed. Only the Agent or their Trusted Agents and Applications can see the Registries listed by them.
Agent | Public | Trusted Agents | Other Agents Granted Access | ||
---|---|---|---|---|---|
Resource | Access | Access | Access | Subject | Access |
/profile/
| Control | - | Control | - | - |
-- id
| Control | Read | Control | - | - |
-- application
| Control | - | Control | - | - |
-- data
| Control | - | Control | - | - |
-- access
| Control | - | Control | - | - |
-- receipt
| Control | - | Control | - | - |
-- remote
| Control | - | Control | - | - |
3. Application
3.1. Overview
Applications are pieces of software that Agents use to access, manipulate, and manage the data in their control, and the data they’ve been granted access to.
An Application is denoted by an identity. Dereferencing that identity leads to an Application profile instance, and a graph of useful information about them.
The information in the Application profile is used during § 4 Application Registration and § 6 Data Authorization to help Agents determine whether they want to use the Application, what kind of data it needs access to, and whether they’ll willing to give it that access.
The Application profile is designed to be publicly accessible.
3.2. Data Model
3.2.1. Summary
An Application provides summary detail about itself, and its author, via properties in the Application class.
An Application identifies the types of data it requires access to by linking to Access Need Groups via the interop:hasAccessNeedGroup property.
3.2.2. Application
An Application is a piece of software that an Agent uses to access, manipulate, and manage the data in their control, as well as the data they’ve been granted access to.
Application | ||
---|---|---|
Property | Range | Description |
applicationName | xsd:string | Name of the Application |
applicationDescription | xsd:string | Description of the Application |
applicationAuthor | Agent | Agent that authored the Application |
applicationAuthorName | xsd:string | Name of the Author |
applicationThumbnail | binary image | Thumbnail for the Application |
hasAccessNeedGroup | AccessNeedGroup | Access Need Group representing types of data the Application needs to operate |
receivesAccessReceipt | interop:ReceiptInMessage, interop:ReceiptInRegistration | Identifies whether Access Receipts should be sent directly to the Application or provided in the Application Registration |
The ApplicationShape is used to validate an instance of the Application class.
<#ApplicationShape> { a [ interop: Application ] ; interop: applicationName xsd: string ; interop: applicationDescription xsd: string ; interop: applicationAuthor IRI; interop: applicationAuthorName xsd: string ; interop: applicationThumbanil IRI?; interop: hasAccessNeedGroup IRI*; interop: receivesAccessReceipt [ interop: ReceiptInMessage interop: ReceiptInRegistration ] }
The ApplicationTree is assigned to a resource to ensure it will validate against the ApplicationShape.
<#ApplicationTree> a st: ShapeTree ; st: expectsType st: ShapeTreeResource ; st: validatedBy <interops#ApplicationShape> .
3.3. Resource Hierarchy
Resource | Class | Shape | Shape Tree |
---|---|---|---|
/profile/
| - | - | ApplicationProfileTree |
-- id#app
| Application | ApplicationShape | ApplicationTree |
-- thumb.svg
| - | - | - |
Application resources MAY use any resource or subject names. The names used herein have been selected for comprehension and readability.
3.4. Permission Model
The permission model for the resources detailed in § 2.3 Resource Hierarchy are illustrated in the table below.
Notable items:
-
The identity profile document
id
which contains the Application instance gives the public read-only access. -
The thumbnail resource
thumb.svg
gives the public read-only access.
Agent | Public | Trusted Agents | Other Agents Granted Access | ||
---|---|---|---|---|---|
Resource | Access | Access | Access | Subject | Access |
/profile/
| Control | - | - | - | - |
-- id
| Control | Read | - | - | - |
-- thumb.svg
| Control | Read | - | - | - |
3.5. Application Services
3.5.1. Load Application Service
Detail how an application service is looked up in the Application Profile.
3.5.2. Redirect to Application Service
Detail how an Agent can be redirected to an application service
3.5.3. Return from Application Service
detail how an Agent is returned back from an application service
4. Application Registration
4.1. Overview
Application Registration lets Agents register and track the Applications they’ve decided to use. It provides a dedicated place to store internal data specific to the function of a given Application.
However, some data is extremely specific to the function of a particular Application, and has absolutely no value to any others. Forcing that data into standard types and structures can lead to mixing in with the interoperable data, creating convoluted vocabularies, shape trees, and shapes that inhibit adoption by others.
Giving Applications a private space where they can store internal data is therefore a key factor in broad interoperability, because it protects interoperable data from pollution by narrowly focused elements.
4.2. Data Model
4.2.1. Summary
An Agent links to Application Registry Sets via the interop:hasApplicationRegistrySet property.
An Application Registry Set links to any number of Application Registries via the interop:hasRegistry property.
Each Application an Agent registers has an Application Registration. An Application Registry links to any number of Application Registrations via the interop:hasRegistration property.
4.2.2. Application Registry Set
An Application Registry Set is a Registry Set specifically made up of Application Registries.
ApplicationRegistrySet a rdfs:subClassOf RegistrySet | ||
---|---|---|
Property | Range | Description |
hasRegistry | Registry | Link to associated Application Registries |
The ApplicationRegistrySetShape is used to validate an instance of the ApplicationRegistrySet class.
<#ApplicationRegistrySetShape> { a [ interop: ApplicationRegistrySet ] ; interop: hasRegistry IRI+}
The ApplicationRegistrySetTree is assigned to a resource to ensure it will validate against the ApplicationRegistrySetShape.
<#ApplicationRegistrySetTree> a st: ShapeTree ; st: expectsType st: ShapeTreeResource ; st: validatedBy <interops#ApplicationRegistrySetShape> .
4.2.3. Application Registry
An Application Registry is a collection of Application Registrations stored in a specific location in a pod.
ApplicationRegistry a rdfs:subClassOf Registry | ||
---|---|---|
Property | Range | Description |
hasRegistration | ApplicationRegistration | Link to an associated Application Registration |
The ApplicationRegistryShape is used to validate an instance of the ApplicationRegistry class.
<#ApplicationRegistryShape> { a [ interop: ApplicationRegistry ] ; interop: hasRegistration IRI*}
The ApplicationRegistryTree is assigned to a container resource to ensure that it will validate against the ApplicationRegistryShape, and contain only conformant instances of the ApplicationRegistrationTree.
<#ApplicationRegistryTree> a st: ShapeTree ; st: expectsType st: ShapeTreeContainer ; st: validatedBy <interops#ApplicationRegistryShape> ; st: contains <#ApplicationRegistrationTree> , st: AllowNone .
4.2.4. Application Registration
An Application Registration provides the Agent with a place to maintain metadata, state, preferences, and other application-specific data associated with a given Application they have elected to use.
ApplicationRegistration a rdfs:subClassOf Registration | ||
---|---|---|
Property | Range | Description |
registeredBy | Agent | Agent that registered the Application Registration |
registeredWith | Application | Application used to create the Application Registration |
registeredAt | xsd:dateTime | Date and time the Application Registration was created |
updatedAt | xsd:dateTime | Date and time the Application Registration was updated |
registeredApplication | Application | The Application that was registered |
hasAccessReceipt | AccessReceipt | An Access Receipt that lets the Application know what the Agent has granted them access to |
The ApplicationRegistrationShape is used to validate an instance of the ApplicationRegistration class.
<#ApplicationRegistrationShape> { a [ interop: ApplicationRegistration ] ; interop: registeredBy IRI; interop: registeredWith IRI; interop: registeredAt xsd: dateTime ; interop: updatedAt xsd: dateTime ; interop: registeredApplication IRI; interop: hasAccessReceipt IRI?}
The ApplicationRegistrationTree is assigned to a resource via the ApplicationRegistryTree, to ensure that the Application Registration will validate against the ApplicationRegistrationShape. It can include any resources, but ensures that if an Access Receipt is added, it is validated against AccessReceiptTree.
<#ApplicationRegistrationTree> a st: ShapeTree ; st: expectsType st: ShapeTreeContainer ; st: validatedBy <interops#ApplicationRegistrationShape> ; st: contains <#AccessReceiptTree> , st: AllowAll .
4.3. Resource Hierarchy
The Application Registry Set and the Application Registry MAY or MAY NOT be on the same pod.
Application Registry Set and Application Registry resources MAY use any resource or subject names.
The resource name for an Application Registration container MUST be a SHA-256 hash encoding of the identity for the registered Application, which is linked via interop:registeredApplication.
-
Example Application Identity:
https://app.example/profile/id#agent
SHA-256 Hash:
705563552198b6fb3efc40717872aa2ec35d669c1095cc5d665f499ec5d7e23a
Is it necessary to use a one-way hash for application registration resource names. Github issue
Application Registrations use containers so that registered Applications have dedicated space to store internal, non-interoperable
data. In the figure above, we can see an application-specific cache
resource (ex-cache-1122
) and an internal index (ex-internal-idx
).
4.4. Permission Model
The permission model for the resources detailed in § 4.3 Resource Hierarchy are illustrated in the table below.
Notable items:
-
There is no public access to any data in an Application Registry
-
Only the Agent or Trusted Agents have the ability to manage contents and permissions across Application Registries, including the creation and modification of Application Registrations.
-
A given registered Application has Read,Append+ access to its Application Registration, Access Receipt, and read/write access to the remaining data space inside of the container. It does not get control privileges.
Note: Append+ indicates that Read/Write is granted to the subsequently created resource.
Agent | Public | Trusted Agents | Other Agents | |||
---|---|---|---|---|---|---|
Resource | Access | Access | Access | Subject | Access | |
/profile/
| - | Control | - | Control | - | - |
-- application
| Application Registry Set | Control | - | Control | - | - |
/applications/
| Application Registry | Control | - | Control | - | - |
-- 70556355...c5d7e23a
| Application Registration | Control | - | Control | Registered Application | Read/Append+ |
---- 04ca5ba7...f3a25ba0
| Access Receipt | Control | - | Control | Registered Application | Read |
---- ex-cache-1122
| - | Control | - | Control | Registered Application | Read/Write |
-- ede6aa50...830e2a42
| Application Registration | Control | - | Control | Registered Application | Read/Append+ |
---- 2af133d6...78e343ba
| Access Receipt | Control | - | Control | Registered Application | Read |
---- ex-internal-idx
| - | Control | - | Control | Registered Application | Read/Write |
-- 150dca42...5b640673
| Application Registration | Control | - | Control | Registered Application | Read/Append+ |
---- 14f8bfb9...e42f7084
| Access Receipt | Control | - | Control | Registered Application | Read |
-- b3564e72...0069f536
| Application Registration | Control | - | Control | Registered Application | Read/Append+ |
4.5. Operations
4.5.1. Load Application Registration
This operation allows an Application find and load a corresponding Application Registration for a given Agent.
Failure to discover an Application Registration means that the Application is not registered.
Per the § 4.4 Permission Model, a given Application will only have access to its own Application Registration. Since Applications do not have access to the list of Applications in an Agent’s Application Registries, they must perform a direct lookup in the addressable space of each Application Registry in the Application Registry Set to find a corresponding Application Registration.
Note: This specification is designed to support compartmentalization of data between Applications. Server-side support may vary. See § 11.1 Application Authorization.
4.5.1.1. Inputs
-
Let
AGENT
be the Agent -
Let
APP
be an Application in use byAGENT
4.5.1.2. Outputs
4.5.1.3. Operation Details
-
AGENT
provides their identity toAPP
-
APP
dereferences the identity ofAGENT
getAGENT
's identity profile document. -
Let
ARSET
be the Application Registry Set linked viaAGENT hasApplicationRegistrySet
.-
Because
ARSET
is a non-public document,AGENT
andAPP
will be required to furnish a DPoP proof and access token to the Solid Server, obtained via the Solid-OIDC protocol.
-
-
For each Application Registry
AREGISTRY
inARSET
-
Let
IDSHA256
be the SHA-256 hash ofAPP
's identity -
Let
STATUS
be theHTTP
status code returned from aGET
orHEAD
ofhttps://AREGISTRY/IDSHA256
-
Return
AREGISTRY
ifSTATUS
is200 OK
-
-
Return FALSE
4.5.2. Register Application
This operation creates a new Application Registration, and MUST
be called from an § 6.2.2 Application Requests Access workfow.
4.5.2.1. Inputs
-
Let
AGENT
be the Agent -
Let
APP
be an Application in use byAGENT
-
Let
REGISTRY
be the target Application Registry
4.5.2.2. Outputs
4.5.2.3. Operation Details
-
Let
EXISTING
be an Application Registration returned from § 4.5.1 Load Application Registration with inputs:AGENT
,APP
-
Return
EXISTING
ifEXISTING
is not empty -
Let
REG
be a newly initialized Application Registration -
Let
REG registeredBy
beAGENT
-
Let
REG registeredWith
be the identity of the Application executing the operation -
Let
REG registeredAt
be the current date and time -
Let
REG updatedAt
be the current date and time -
Let
REG registeredApplication
be the identity ofAPP
-
Let
IDSHA256
be the SHA-256 hash ofAPP
's identity -
Add
REG
to theREGISTRY
container, usingIDSHA256
as the resource name -
Assign permissions for
REG
per the § 4.4 Permission Model -
Link
REG
toREGISTRY
viaREGISTRY hasRegistration
-
Return
REG
4.6. Application Services
4.6.1. Register Application
Define app registration service
5. Data Registration
5.1. Overview
Data Registration lets Agents store and manage the data they control. Data of various types is organized and stored in a uniform way to aid validation, authorization, discovery, and more.
Complex hierarchies that hinder interoperability are avoided by storing data in a relatively flat hierarchy. This creates natural data boundaries that make data storage and authorization more intuitive.
5.2. Data Model
5.2.1. Summary
An Agent links to a Data Registry Set via the interop:hasDataRegistrySet property.
A Data Registry Set links to any number of Data Registries via the interop:hasRegistry property.
A Data Registry links to any number of Data Registrations via the interop:hasRegistration property.
There is a Data Registration for each unique type of stored data. Each Data Registration contains and links to any number of Data Instances via the ldp:contains property.
5.2.2. Data Registry Set
A Data Registry Set is a Registry Set specifically made up of Data Registries.
DataRegistrySet a rdfs:subClassOf RegistrySet | ||
---|---|---|
Property | Range | Description |
hasRegistry | Registry | Link to associated Data Registries |
The DataRegistrySetShape is used to validate an instance of the DataRegistrySet class.
<#DataRegistrySetShape> { a [ interop: DataRegistrySet ] ; interop: hasRegistry IRI+}
The DataRegistrySetTree is assigned to a resource to ensure it will validate against the DataRegistrySetShape.
<#DataRegistrySetTree> a st: ShapeTree ; st: expectsType st: ShapeTreeResource ; st: validatedBy <interops#DataRegistrySetShape> .
5.2.3. Data Registry
A Data Registry is a collection of Data Registrations, each representing a unique type of data associated with a given shape tree.
A Data Registry can be used for basic discovery, but it is not designed nor intended to be an efficient means to query or index data. However, it is intended to be used as reliable source data for different query engines or indexing schemes.
DataRegistry a rdfs:subClassOf Registry | ||
---|---|---|
Property | Range | Description |
hasRegistration | DataRegistration | Link to an associated Data Registration |
The DataRegistryShape is used to validate an instance of the DataRegistry class.
<#DataRegistryShape> { a [ interop: DataRegistry ] ; interop: hasRegistration IRI*}
The DataRegistryTree is assigned to a container resource to ensure that it will validate against the DataRegistryShape, and contain only conformant instances of the DataRegistrationTree.
<#DataRegistryTree> a st: ShapeTree ; st: expectsType st: ShapeTreeContainer ; st: validatedBy <interops#DataRegistryShape> ; st: contains <#DataRegistrationTree> , st: AllowNone .
5.2.4. Data Registration
A Data Registration provides the Agent with a place to store Data Instances of a particular type, conforming to a given shape tree, indicated by the interop:registeredShapeTree property.
A Data Instance is a unique, stored instance of a particular type of data, conforming to the shape tree for the instance’s Data Registration.
DataRegistration a rdfs:subClassOf Registration | ||
---|---|---|
Property | Range | Description |
registeredBy | Agent | Agent that registered the Data Registration |
registeredWith | Application | Application used to create the Data Registration |
registeredAt | xsd:dateTime | Date and time the Data Registration was created |
updatedAt | xsd:dateTime | Date and time the Data Registration was updated |
registeredShapeTree | st:ShapeTree | The Shape Tree that was registered |
registeredType | rdf:type | Type of data registered |
The DataRegistrationShape is used to validate an instance of the DataRegistration class.
<#DataRegistrationShape> { a [ interop: DataRegistration ] ; interop: registeredBy IRI; interop: registeredWith IRI; interop: registeredAt xsd: dateTime ; interop: updatedAt xsd: dateTime ; interop: registeredShapeTree IRI; interop: registeredType IRI*}
The DataRegistrationTree is assigned to a resource via the DataRegistryTree, to ensure that the Data Registration will validate against the DataRegistrationShape.
<#DataRegistrationTree> a st: ShapeTree ; st: expectsType st: ShapeTreeContainer ; st: validatedBy <interops#DataRegistrationShape> .
5.3. Resource Hierarchy
The Data Registry Set and the Data Registry MAY or MAY NOT be on the same pod.
Data Registry Set and Data Registry resources MAY use any resource or subject names.
Data Registrations and Data Instances MUST use UUIDs for resource names.
A Data Registration container MUST contain conformant instances of the shape tree associated with the Data Registration via interop:registeredShapeTree.
Two complementary shape trees MUST be assigned to the same Data Registration container to ensure that it conforms to general validation requirements, and to ensure that it only contains Data Instances of the registered shape tree identified by interop:registeredShapeTree.
In the figure below, the combination of a DataRegistrationTree and FooContainingTree on the same Data Registration can be observed. Furthermore, an example of a contained Data Instance is provided, which conforms to FooTree per the directive in FooContainingTree.
-- 8501f084-deb9-4775-8a35-2040df435d21/#registration
| |
Contents of the Data Registration
|
Ensure the container resource for the Data Registration conforms to interops#DataRegistrationShape .
And also ensure the Data Registration only
contains resources that conform to
|
------ 16e1eae9-20a5-489d-8380-8c07ca3805c4#foo
| |
Contents of the Data Instance
|
Ensure the resource for the Data Instance conforms to <#FooTree> .
|
5.4. Permission Model
Almost all of the collaborative use cases between Agents in the ecosystem are based on data furnished through the Data Registry.
Only the Agent or Trusted Agents have the ability to manage contents and permissions across Data Registries, including the creation and modification of Data Registrations. The table below illustrates this using the resource hierarchy from the previous section. Other Agents are granted varying levels of access by the Agent or their Trusted Agents.
Note: § 6 Data Authorization provides patterns for managing Access Grants and sending Access Receipts to the Agents who were granted access.
Agent | Public | Trusted Agents | Other Agents | |||
---|---|---|---|---|---|---|
Resource | Access | Access | Access | Subject | Access | |
/profile/
| - | Control | - | Control | - | - |
-- data
| Data Registry Set | Control | - | Control | - | - |
/data/
| Data Registry | Control | - | Control | - | - |
-- 8501f084...2040df43
| Data Registration | Control | Varies | Control | Grantee | Varies |
---- 16e1eae9...ca3805c4
| Data Instance | Control | Varies | Control | Grantee | Varies |
---- 886785d2...5ac36b7b
| Data Instance | Control | Varies | Control | Grantee | Varies |
---- dae5015c...7ca7a198
| Data Instance | Control | Varies | Control | Grantee | Varies |
-- df4ab227...fad10fb9
| Data Registration | Control | Varies | Control | Grantee | Varies |
---- 9b60a354...cb9da85c
| Data Instance | Control | Varies | Control | Grantee | Varies |
---- 6e545b74...b15cbdce
| Data Instance | Control | Varies | Control | Grantee | Varies |
---- d33e01c8...ac9e3cc6
| Data Instance | Control | Varies | Control | Grantee | Varies |
---- 927108fa...14985cb9
| Data Instance | Control | Varies | Control | Grantee | Varies |
---- 180dda0b...c4f8c4dc
| Data Instance | Control | Varies | Control | Grantee | Varies |
-- 3c9c9cff...fc7f916b
| Data Registration | Control | Varies | Control | Grantee | Varies |
---- 4376595a...f8d2547c
| Data Instance | Control | Varies | Control | Grantee | Varies |
---- 14c9fc6a...7f6de3ca
| Data Instance | Control | Varies | Control | Grantee | Varies |
A signficant amount of flexibility is needed in granting other Agents access to data in the registry. It is also important to avoid the creation of permission swamps that are unwieldy for Agents to manage.
Organizing data by shape tree creates natural permission boundaries, making authorization more intuitive and manageable.
Access is granted to a certain type of data by granting access to the entire Data Registration, or to specific Data Instances within it.
Note: [WAC] doesn’t have any mechanism to extend or modify inherited permissions. Access Control Policies (ACP) is recommended for optimal results.
5.4.1. Access to a Data Registration
Access granted at the Data Registration level applies to all Data Instances within it.
The access modes listed in the table below can be combined as needed.
Mode | Resultant Access |
---|---|
Read | Can read all existing and yet to be created Data Instances. Includes being able to see the full list of Data Instances in the registration. |
Write | Can modify the Data Registration, and all existing Data Instances within it. Can create new Data Instances, and can delete them. |
Append | Can only create new Data Instances within the Data Registration. |
Read Permissions | Can read permissions on the Data Registration, as well as any Data Instances within it. |
Write Permissions | Can change permissions on the Data Registration, as well as any Data Instances within it. |
5.4.2. Access to Specific Data Instances
Access granted at the Data Instance level apply only to that instance, and the resources within it.
The access modes listed in the table below can be combined as needed.
Mode | Resultant Access |
---|---|
Read | Can list and read all resources within the Data Instance. |
Write | Can modify the Data Instance and any resources within it, including creating and deleting resources. |
Append | Can create resources within the Data Instance. Can add to a resource in the Data Instance but cannot remove anything from it, or delete it. |
Read Permissions | Can read permissions on the Data Instance and any resources within it. |
Write Permissions | Can change permissions on the Data Instance and any resources within it. |
5.5. Operations
Registering data in a Data Registry is primarily concerned with the following two operations:
-
Registering new data types as Data Registrations
-
Storing and registering new instances of those data types as Data Instances
The following operations allow for the lookup, creation, and deletion of Data Registrations and Data Instances in a Data Registry.
-
§ 5.5.1 Load Data Registration - Load an existing Data Registration
-
§ 5.5.2 Create Data Registration - Create a new Data Registration
-
§ 5.5.3 Create Data Instance - Create a new Data Instance for a given Data Registration
-
§ 5.5.4 Delete Data Registration - Delete a Data Registration
-
§ 5.5.5 Delete Data Instance - Delete a Data Instance for a given Data Registration
Note: Managing Data Registrations and the Data Instances contained within them is inextricably linked to permissioning the data for effective use and secure collaboration. This is covered at length in § 6 Data Authorization.
5.5.1. Load Data Registration
Description | |||
---|---|---|---|
This operation returns a Data Registration the corresponds
to a given shape tree in a Data Registry.
Inputs
| | ||
TREE
| Shape tree to match against | ||
REGISTRY
| Data Registry to look for a match within
Outputs
| | |
Data Registration | Loaded by matching against TREE in REGISTRY
|
-
MUST return
404
ifTREE
orREGISTRY
cannot be successfully dereferenced. -
For each Data Registration
REGISTRATION
included inREGISTRY hasRegistration
-
return
REGISTRATION
ifREGISTRATION registeredShapeTree
==TREE
-
5.5.2. Create Data Registration
Description | |||
---|---|---|---|
This operation creates a new Data Registration in a Data Registry for a specific shape tree.
Inputs
| | ||
TREE
| Shape tree to register | ||
TYPE
| Optional rdf:type to associate with the registration | ||
REGISTRY
| Data Registry where the registration will be created
Outputs
| | |
Data Registration | Created for TREE in REGISTRY
|
-
MUST return
404
ifTREE
orREGISTRY
cannot be successfully dereferenced. -
MUST return
400
if an existing Data Registration is returned from § 5.5.1 Load Data Registration with inputs:TREE
,REGISTRY
-
Let
REG
be a newly initialized Data Registration -
Let
REG registeredBy
be the current Agent -
Let
REG registeredWith
be the identity of the Application executing the operation -
Let
REG registeredAt
be the current date and time -
Let
REG updatedAt
be the current date and time -
Let
REG registeredShapeTree
beTREE
-
Let
REG registeredType
beTYPE
ifTYPE
is not empty -
PUT
REG
into theREGISTRY
container -
Assign permissions for
REG
per the § 5.4 Permission Model -
Link
REG
toREGISTRY
viaREGISTRY hasRegistration
-
Return
REG
5.5.3. Create Data Instance
Description | |||
---|---|---|---|
This operation will create a new Data Instance for
a given Data Registration. It must be a conformant instance of
the shape tree registered with the Data Registration, per
the validation structure detailed in § 5.3 Resource Hierarchy.
Assumes that a Data Registration has already been loaded by § 5.5.1 Load Data Registration and provided as input. Inputs
| | ||
REGISTRATION
| Data Registration to associated the new Data Instance with | ||
INSTANCE
| Instance corresponding with REGISTRATION registeredShapeTree
Outputs
| | |
Data Instance | Created for REGISTRATION in REGISTRY
|
-
PUT
INSTANCE
into theREGISTRATION
container-
A UUID MUST be assigned as the resource name.
-
A target shape tree MUST be assigned via the
rel=http://shapetrees.org/#targetShapeTree
HTTP Link relation -
A focus node for shape tree validation MUST be assigned via the
rel=http://shapetrees.org/#FocusNode
HTTP Link relation
-
-
Return
INSTANCE
5.5.4. Delete Data Registration
Description | |||
---|---|---|---|
This operation deletes a Data Registration from a Data Registry.
Inputs
| | ||
REGISTRATION
| Data Registration to delete | ||
REGISTRY
| Data Registry of REGISTRATION
Outputs
| | |
HTTP Status Code | As returned from server |
-
MUST return
404
ifREGISTRATION
cannot be successfully dereferenced. -
MUST return
400
ifREGISTRATION
contains one or more Data Instances. -
Remove
REGISTRATION
from the graph ofREGISTRY
viaREGISTRY hasRegistration
-
DELETE
REGISTRATION
Cleanup of related data may need to be specified
5.5.5. Delete Data Instance
Description | |||
---|---|---|---|
This operation deletes a Data Instance from a Data Registration.
Inputs
| | ||
INSTANCE
| Data Instance to delete
Outputs
| | |
HTTP Status Code | As returned from server |
-
MUST return
404
ifINSTANCE
cannot be successfully dereferenced. -
If
INSTANCE
is a container-
Let
RESOURCES
be a hierarchy of all resources contained byINSTANCE
, including any child containers and resources. -
DELETE each
RESOURCE
inRESOURCES
, iterating up from the bottom of theRESOURCES
hierarchy
-
-
DELETE
INSTANCE
Cleanup of related data may need to be specified
6. Data Authorization
6.1. Overview
The ability for one Agent to grant others access to data in their control is a fundamental element of a collaborative interoperable ecosystem.
Data Authorization represents several key elements that work together to grant, adjust, and rescind access to data controlled by an ecosystem participant.
-
A common way to express § 7 Access Needs allows ecosystem participants to convey the types or specific instances of data they require.
-
§ 8 Access Grants record access decisions made by an Agent on the data in their control.
-
§ 9 Access Receipts reflect Access Grants that one Agent has provided to another Agent
6.2. Workflows
The following workflows represent the authorization patterns enabled by this specification.
6.2.1. Presenting an Access Grant
Note: All user experience herein is meant to inform how the data model and operations work. The design and style should be considered non-normative. Example data has been incorporated into the provided designs to further comprehension of the proposed workflow.
-
Let
GRANT
be an existing Access Grant forSUBJECT
returned by § 8.4.6 Load Grant-
If
GRANT
is missing, create one via § 8.4.1 Initialize Grant
-
-
Present information about the Application
APP
if the Access Grant Subject is for an Application:-
Application Name -
APP applicationName
-
Application Identity -
APP
URI -
Application Author Name -
APP applicationAuthorName
-
Application Author Identity -
APP applicationAuthor
-
Application Thumbnail -
APP applicationThumbnail
-
Application Summary -
APP applicationDescription
-
-
Present information about the Agent
AGENT
if the Access Grant Subject is not an Application-
Agent Name
AGENT fullName
-
Agent Identity -
AGENT
URI
-
-
Call § 6.2.1.1 Presenting an Access Need Group for each Access Need Group linked via
GRANT hasAccessNeedGroup
. -
Present an option to authorize the grant by calling § 8.4.8 Record Grant, or cancel.
6.2.1.1. Presenting an Access Need Group
Description | |||
---|---|---|---|
This sub-operation of § 6.2.1 Presenting an Access Grant presents an
input Access Need Group associated with a specific Access Grant.
Each Access Need Group represents a set of Access Needs and/or Trusted Needs. Inputs
| | ||
GROUP
| The Access Need Group to present | ||
GRANT
| The Access Grant that GROUP is linked to
|
-
Let
GDEC
be the Access Need Group Decorator linked viaGROUP hasAccessNeedGroupDecorator
-
Present information about the Access Need Group
GROUP
-
Group Name -
GDEC skos:prefLabel
-
Group Description -
GDEC skos:definition
-
Grantee Type -
GROUP authenticatesAs
-
Necessity -
GROUP accessNecessity
-
-
Allow
GROUP
to be disabled via § 8.4.22 Deny Access Need Group if group necessity is optional -
For each Access Need
NEED
linked viaGROUP hasAccessNeed
-
For each Trusted Need
TNEED
linked viaGROUP hasTrustedNeed
6.2.1.2. Presenting a Data Access Need
Description | |||
---|---|---|---|
This sub-operation of § 6.2.1.1 Presenting an Access Need Group presents an Access Need for an input Access Need Group.
Each discrete Access Need is related to a specific type of data, identified by a shape tree. Each Access Need directly linked to an Access Need Group may have zero or more Referenced Access Needs associated with it. Each Referenced Access Need is presented under the Access Need it is linked to. The controller can grant access to all data for the Access Need and the Referenced Access Needs, select specific instances of the Access Need and narrow the Referenced Access Need instances to only those related. Manual selection with no inheritance can also be done instead. Access to which data has been shared with the controller in their Remote Data Registry is also requested through Access Needs. In most cases, controllers won’t need to do fine-grained instance selection of remote data, but should be allowed the ability if they desire. Inputs
| | ||
NEED
| The Access Need to present | ||
GROUP
| The Access Need Group that NEED is linked to
| ||
GRANT
| The Access Grant that GROUP is linked to
|
-
Call § 6.2.1.2.1 Presenting Data Access Need Details to explain the Access Need
-
Let
DG
be the Data Grant linked viaNEED hasDataGrant
-
Manage the scope of data to be granted
DG scopeOfGrant
:-
No Access -
interop:NoAccess
(if necessity is optional)-
Enable via § 8.4.23 Deny Data Grant
-
-
All Current and Future -
interop:AllInstances
-
Enable via § 8.4.25 Select All Data Instances
-
-
Only Selected Instances -
interop:SelectedInstances
-
Present existing Data Instances corresponding to
DG registeredShapeTree
, identifying any existing selections linked viaDG hasDataInstance
-
Allow one or more to be chosen
-
Enable via § 8.4.27 Select Specific Data Instance, providing each selected Data Instance
-
-
-
For each Referenced Access Need
REFNEED
linked viaNEED hasReferencedAccessNeed
-
Let
REFDG
be the Referenced Data Grant linked viaNEED hasReferencedDataGrant
-
Call § 6.2.1.2.1 Presenting Data Access Need Details to explain the Referenced Access Need
-
Manage the scope of data to be granted
REFDG scopeOfGrant
:-
No Access -
interop:NoAccess
(if necessity is optional)-
Enable via § 8.4.24 Deny Referenced Data Grant
-
-
All Current and Future -
interop:AllInstances
-
Only Inherited Instances -
interop:InheritInstances
(ifDG scopeOfGrant
isinterop:SelectedInstances
)-
Present Data Instances of
REFNEED registeredShapeTree
linked to all Data Instances forDG
viast:traverseViaShapePath
ofDG registeredShapeTree
-
-
Only Selected Instances -
interop:SelectedInstances
-
Present existing Data Instances corresponding to
REFDG registeredShapeTree
, identifying any existing selections linked viaREFDG hasDataInstance
-
Allow one or more to be chosen
-
Enable via § 8.4.29 Select Specific Referenced Data Instance, providing each selected Data Instance.
-
-
-
-
Note: Access to data in the Remote Data Registry is similarly managed per Access Need. User interfaces may opt to present simpler options, and mix the selection in with local data, like in the figure above. However, for the comprehension and completeness, options for remote data access are presented as follows:
-
Let
RDG
be the Remote Data Grant linked viaNEED hasRemoteDataGrant
-
Manage the scope of data to be granted
RDG scopeOfGrant
:-
No Access -
interop:NoAccess
(if necessity is optional)-
Enable via § 8.4.36 Deny Remote Data Grant
-
-
All Remote Data -
interop:AllRemote
-
Enable via § 8.4.30 Select All Remote Instances
-
-
All Remote From Agent -
interop:AllRemoteFromAgent
-
Present existing Remote Agent Data Registrations corresponding to
NEED registeredShapeTree
, identifying any existing selections linked viaRDG hasRemoteDataFromAgent
-
Allow one or more to be chosen
-
Enable via § 8.4.32 Select All Remote From Agent
-
-
Only Selected Remote Data -
interop:SelectedRemote
-
Present existing Data Grants and/or Referenced Data Grants, corresponding to
NEED registeredShapeTree
and optionally organized by Remote Agent Data Registrations, identifying any existing selections linked viaRDG hasDataGrant
and/orRDG:hasReferencedDataGrant
-
Allow one or more to be chosen
-
Enable via § 8.4.34 Select Specific Remote Agent Data Grants, providing the selected Data Grants and/or Referenced Data Grants.
-
-
-
For each Referenced Access Need
REFNEED
linked viaNEED hasReferencedAccessNeed
-
Let
REFRDG
be the Referenced Remote Data Grant linked viaNEED hasReferencedRemoteDataGrant
-
Manage the scope of data to be granted
REFRDG scopeOfGrant
:-
No Access -
interop:NoAccess
(if necessity is optional)-
Enable via § 8.4.37 Deny Referenced Remote Data Grant
-
-
All Remote Data -
interop:AllRemote
-
All Remote From Agent -
interop:AllRemoteFromAgent
-
Present existing Remote Agent Data Registrations corresponding to
NEED registeredShapeTree
, identifying any existing selections linked viaREFRDG hasRemoteDataFromAgent
-
Allow one or more to be chosen
-
-
Only Selected Remote Data -
interop:SelectedRemote
-
Present existing Data Grants and/or Referenced Data Grants, corresponding to
NEED registeredShapeTree
and optionally organized by Remote Agent Data Registrations, identifying any existing selections linked viaREFRDG hasDataGrant
and/orREFRDG hasReferencedDataGrant
-
Allow one or more to be chosen
-
Enable via § 8.4.35 Select Specific Referenced Remote Agent Data Instances, providing the selected Data Grants and/or Referenced Data Grants.
-
-
-
6.2.1.2.1. Presenting Data Access Need Details
Description | |||
---|---|---|---|
This sub-operation of § 6.2.1.2 Presenting a Data Access Need is used to present specific
details of an Access Need or Referenced Access Need.
Inputs
| | ||
NEED
| The Access Need or Referenced Access Need to present |
-
Let
STDEC
be the Shape Tree Decorator linked viaNEED hasShapeTreeDecorator
-
Let
ANDEC
be the Access Need Decorator linked viaNEED hasAccessNeedDecorator
-
Present information about the Access Need:
-
Shape Tree Name -
STDEC skos:prefLabel
-
Shape Tree Description -
STDEC skos:definition
-
Access Modes -
NEED accessMode
s -
Necessity -
NEED accessNecessity
-
6.2.1.3. Presenting a Trusted Need
Description | |||
---|---|---|---|
This workflow explains how to present a Trusted Need for
an input Access Need Group associated with a given Access Grant.
Each discrete Trusted Need is related to a specific type of trusted resource. Inputs
| | ||
TNEED
| The Trusted Need to present | ||
GROUP
| The Access Need Group that TNEED is linked to
| ||
GRANT
| The Access Grant that GROUP is linked to
|
-
Let
TNEED
be the Access Need Decorator linked viaTNEED hasAccessNeedDecorator
-
Let
TG
be the Trusted Grant linked viaTNEED hasTrustedGrant
-
Present information about the Trusted Need:
-
Trusted Need Type -
STDEC skos:prefLabel
-
Trusted Need Description -
STDEC skos:definition
-
Access Modes -
TNEED accessMode
s -
Necessity -
TNEED accessNecessity
-
-
Manage the scope of the trusted grant
TG scopeOfGrant
:-
Next if
TNEED trustedWithType
isinterop:Agent
-
All Registries - where
rdf:type
of Registry isTNEED trustedWithType
-
Enable via § 8.4.38 Select Trusted Registry Set
-
-
Specific TYPE Registries
-
Present existing Registries where
rdf:type
isTNEED trustedWithType
-
Allow one or more Registries to be chosen
-
Enable via § 8.4.39 Select Specific Trusted Registry, providing each selected Registrys
-
-
6.2.2. Application Requests Access
Let CONTROLLER
be an Agent that wants to give an Application APP
access to data in their control.
Let APP
be the Application that CONTROLLER
wishes to use, and must
grant access to. APP
may be an Application that is piloted by the Agent, or it may be an autonomous service that operates independently.
The following workflow applies to both cases.
Let AUTHZ
be an Application trusted by the Agent for
authorization and access control.
-
CONTROLLER
decides they’d like to useAPP
-
CONTROLLER
provides their identity toAPP
-
APP
dereferences the identity to getCONTROLLER
's identity profile document. -
APP
discovers thatAUTHZ
is an Application that is a Trusted Agent ofCONTROLLER
for data authorization via the § 3.5.1 Load Application Service operation. -
APP
redirectsCONTROLLER
toAUTHZ
via the § 3.5.2 Redirect to Application Service operation.-
Let
APPREG
be an Application Registration returned by § 4.5.1 Load Application Registration with inputs:CONTROLLER
,APP
-
If
APPREG
is empty letAPPREG
be the Application Registration returned by § 4.5.2 Register Application with inputs:AGENT
,APP
,REGISTRY
. -
AUTHZ
looks inAPP
's application profile document for Access Need Groups with aninterop:accessScenario
ofinterop:PersonalAccess
-
Any Access Need Groups found are passed to the § 6.2.1 Presenting an Access Grant workflow, which presents them to
CONTROLLER
. -
CONTROLLER
decides whether to grantAPP
the access requested. -
CONTROLLER
authorizes the requested Access Need Groups and Access Needs:-
The § 8.4.8 Record Grant operation is invoked
-
An Access Grant is stored in
CONTROLLER
's Access Grant Registry. -
§ 8.4.12 Apply Permissions is called to apply permissions based on the Access Grant.
-
§ 9.4.1 Provide Access Receipt is called to store the Access Receipt. The Application has set
interop:receivesAccessReceipt
toReceiptInRegistration
, so the Access Receipt is stored in the Application Registration forAPP
.
-
-
-
AUTHZ
redirectsCONTROLLER
back toAPP
via the § 3.5.3 Return from Application Service operation.
-
6.2.3. Another Agent Requests Access
Let REQUESTER
be an Agent requesting data from another Agent CONTROLLER
with a known identity.
Let REQAPP
be an Application piloted by REQUESTER
Let RAUTHZ
be an Application trusted by REQUESTER
for
authorization and access control.
Let CONTROLLER
be an Agent in control of data that REQUESTER
would like to access.
Let CAUTHZ
be an Application trusted by CONTROLLER
for
authorization and access control.
-
REQUESTER
would like access toCONTROLLER
's data. -
REQUESTER
providesCONTROLLER
's identity toREQAPP
. -
REQAPP
dereferencesCONTROLLER
's identity to getCONTROLLER
's identity profile document. -
REQAPP
uses Access Need Groups from its application profile document with aninterop:accessScenario
ofinterop:SharedAccess
to identify Access Need Groups to request fromCONTROLLER
. -
CONTROLLER
has aninterop:receivesAccessReceipt
value ofReceiptInMessage
in their identity profile document. -
REQAPP
puts the Access Need Groups into an Access Request and posts it to the access inbox identified byinterop:hasAccessInbox
in theCONTROLLER
's identity profile document. -
CAUTHZ
monitorsCONTROLLER
's access inbox autonomously. It notifiesCONTROLLER
when a new Access Request is received.-
CONTROLLER
clicks a link in the notification fromCAUTHZ
, opening theCAUTHZ
user interface and invoking the [[##present-grant]] workflow using the Access Need Groups from the Access Request. -
CONTROLLER
determines whether they wish to grant the access requested. -
Assuming
CONTROLLER
authorizes a minimum of the required Access Need Groups and Access Needs, the § 8.4.8 Record Grant operation is invoked. -
§ 8.4.8 Record Grant stores an Access Grant in
CONTROLLER
's Access Grant Registry.-
§ 8.4.12 Apply Permissions is called to apply permissions based on the Access Grant.
-
§ 9.4.1 Provide Access Receipt is called to deliver the Access Receipt.
-
CAUTHZ
dereferencesREQUESTER
's identity to getREQUESTER
's identity profile document. -
REQUESTER
has setinterop:receivesAccessReceipt
toReceiptInMessage
, so the Access Receipt is posted to the access inbox identified viahasAccessInbox
inREQUESTER
's 'identity profile document.
-
-
-
-
RAUTHZ
monitorsREQUESTER
's access inbox autonomously. It notifiesREQUESTER
when a new Access Receipt is received.-
REQUESTER
clicks the link in the notification, opening theRAUTHZ
user interface, and presenting the Access Receipt toREQUESTER
. -
REQUESTER
accepts the Access Receipt, andRAUTHZ
invokes the § 9.4.4 Record Access Receipt operation.-
§ 9.4.4 Record Access Receipt is called to store the Access Receipt in
REQUESTER
's Access Receipt Registry. -
§ 10.4.3 Update Remote Data is called to update
REQUESTER
's Remote Data Registry to reflect what is in the Access Receipt.
-
-
6.2.4. Controller Shares Access
Let CONTROLLER
be an Agent in control of data that
they would like to authorize RECEIVER
to access.
Let CAPP
be an Application piloted by CONTROLLER
Let CAUTHZ
be an Application trusted by CONTROLLER
for
authorization and access control.
Let RECEIVER
be an Agent receiving access to data from another Agent CONTROLLER
.
Let RAUTHZ
be an Application trusted by RECEIVER
for
authorization and access control.
-
CONTROLLER
would like to giveRECEIVER
access to their data. -
CONTROLLER
providesRECEIVER
's identity toCAPP
. -
CAPP
dereferencesRECEIVER
's identity to getRECEIVER
's identity profile document. -
CAPP
discovers thatCAUTHZ
is an Application that is a Trusted Agent ofCONTROLLER
for data authorization via the § 3.5.1 Load Application Service operation. -
CAPP
redirectsCONTROLLER
toCAUTHZ
via the § 3.5.2 Redirect to Application Service operation.-
CAUTHZ
looks inCAPP
's application profile document for Access Need Groups with aninterop:accessScenario
ofinterop:SharedAccess
-
Any Access Need Groups found are passed to the [[##present-grant]] workflow, which presents them to
CONTROLLER
. -
CONTROLLER
authorizes the data to share withRECEIVER
based on the provided Access Need Groups.-
The § 8.4.8 Record Grant operation is invoked
-
An Access Grant is stored in
CONTROLLER
's Access Grant Registry. -
§ 8.4.12 Apply Permissions is called to apply permissions based on the Access Grant.
-
§ 9.4.1 Provide Access Receipt is called to store the Access Receipt.
RECEIVER
has setinterop:receivesAccessReceipt
toReceiptInMessage
, so the Access Receipt is posted to the access inbox identified viahasAccessInbox
inRECEIVER
's 'identity profile document.
-
-
-
CAUTHZ
redirectsCONTROLLER
back toCAPP
via the § 3.5.3 Return from Application Service operation.
-
-
RAUTHZ
monitorsRECEIVER
's access inbox autonomously. It notifiesRECEIVER
when a new Access Receipt is received.-
RECEIVER
clicks the link in the notification, opening theRAUTHZ
user interface to review the Access Receipt. -
RECEIVER
accepts the Access Receipt, andRAUTHZ
invokes the § 9.4.4 Record Access Receipt operation.-
§ 9.4.4 Record Access Receipt is called to store the Access Receipt in
RECEIVER
's Access Receipt Registry. -
§ 10.4.3 Update Remote Data is called to update
RECEIVER
's Remote Data Registry to reflect what is in the Access Receipt.
-
-
6.2.5. Controller Shares Access with Invited Agent
Controlling Agent initiates sharing their data with an Agent that doesn’t have an identity or a pod.
Let CONTROLLER
be an Agent in control of data that
they would like to authorize INVITEE
to access.
Let CAPP
be an Application piloted by CONTROLLER
Let CAUTHZ
be an Application trusted by CONTROLLER
for
authorization and access control.
Let CISERVICE
be an Application trusted by CONTROLLER
to validate
invitations made to INVITEE
s.
Let INVITEE
be a person without an identity or pod that CONTROLLER
would like to authorize to access their data. CONTROLLER
knows their
e-mail address and mobile phone number.
LET PROVIDER
be a service that hosts identities and pods who
provisions the same for INVITEE
Let PAUTHZ
be an Application offered by PROVIDER
and trusted by INVITEE
for authorization and access control.
-
CONTROLLER
would like to giveINVITEE
access to their data. -
CONTROLLER
providesINVITEE
's e-mail address and mobile number toCAPP
. -
CAPP
discovers thatCAUTHZ
is an Application that is a Trusted Agent ofCONTROLLER
for data authorization via the § 3.5.1 Load Application Service operation. -
CAPP
redirectsCONTROLLER
toCAUTHZ
via the § 3.5.2 Redirect to Application Service operation.-
CAUTHZ
looks inCAPP
's application profile document for Access Need Groups with aninterop:accessScenario
ofinterop:SharedAccess
-
Any Access Need Groups found are passed to the [[##present-grant]] workflow, which presents them to
CONTROLLER
. -
CONTROLLER
authorizes the data to share withINVITEE
based on the provided Access Need Groups.-
The § 8.4.9 Record Invitation operation is invoked
-
An Access Invitation is stored in
CONTROLLER
's Access Grant Registry. -
§ 8.4.10 Deliver Invitation is called to create an invitation entry for each Access Invitation Channel in the Access Invitation with
CISERVICE
-
For each Access Invitation Channel in the Access Invitation
-
CISERVICE
sends a notification toINIVITEE
using the medium associated with the Access Invitation Channel type
-
-
-
-
CAUTHZ
redirectsCONTROLLER
back toCAPP
via the § 3.5.3 Return from Application Service operation.
-
-
INVITEE
receives a notification associated with one of the Access Invitation Channels.-
INVITEE
clicks a link in the notification to register an identity and pod withPROVIDER
. -
INVITEE
clicks a link in the notification bringing them to theCISERVICE
user interface to validate the invitation by invoking § 8.4.11 Validate Invitation.-
If validation is successful, but there are other Access Invitation Channels left to validate, the
INVITEE
will be prompted to validate them. Continue until failure or validation of all Access Invitation Channels are succesful. -
CISERVICE
initializes a new Access Grant via § 8.4.1 Initialize Grant, using the contents of the Access Invitation, and the new registered identity forINVITEE
. -
CISERVICE
calls § 8.4.8 Record Grant using the Access Grant initialized from the Access Invitation-
An Access Grant is stored in
CONTROLLER
's Access Grant Registry. -
§ 8.4.12 Apply Permissions is called to apply permissions based on the Access Grant.
-
§ 9.4.1 Provide Access Receipt is called to store the Access Receipt.
INVITEE
has setinterop:receivesAccessReceipt
toReceiptInMessage
, so the Access Receipt is posted to the access inbox identified viahasAccessInbox
inINVITEE
's 'identity profile document.
-
-
-
Should we assume that CISERVICE is able to manage grants, or should it need to redirect through the authorization agent? Perhaps the recommendation should be that they are combined? Bad separation of concerns?
This doesn’t take account a sequencing of validation steps from one channel to another.
6.3. Application Services
6.3.1. Authorize Data Service
Define data authorization service
7. Access Needs
7.1. Overview
Agents or Applications in the ecosystem often require access to data controlled by some other Agent. Consequently, a common way to explain and communicate data needs between these parties is required.
A given Agent or Application expresses their access needs by providing one or more Access Need Groups to the Agent controlling the data they require access to. The channels through which these may be communicated are detailed in § 6.2 Workflows.
Each Access Need Group is associated with up to three types of needs:
-
Access Needs represent a need to access a particular type of data in a Data Registry or Remote Data Registry, identified by the shape tree type.
-
Trusted Needs represent a need for elevated access to entire Registries, Registry Sets, or the Identity Profile Document for the Agent
Access Need Groups are essential to an Agent’s decision-making when determining whether to grant access, as illustrated in the § 6.2.1 Presenting an Access Grant workflow. They are stored as part of the Access Grant in the Access Grant Registry.
7.2. Data Model
7.2.1. Access Need Group
An Access Need Group is a collection of Access Needs and/or Trusted Needs that a given Agent and/or Application uses to communicate an access request to other Agents.
An Access Need Group links to an Access Decorator Index of different Access Decorator Series that explain the Access Need Group and Access Needs in different languages. Each Access Decorator Series points to an Access Decorator Resource, which contains the actual language-specific content mappings.
AccessNeedGroup | ||
---|---|---|
Property | Range | Description |
hasAccessNeedDecoratorIndex | - | Index of Access Decorator Resources to describe Access Need Groups, Access Needs, and Trusted Needs |
hasAccessNeedGroupDecorator | AccessNeedGroupDecorator | Access Need Group Decorator that describes the Access Need Group |
accessNecessity | interop:AccessRequired , interop:AccessOptional
| Necessity of the access to the requesting party |
accessScenario | interop:PersonalAccess , interop:SharedAccess
| Context in which the access group should be presented |
authenticatesAs | Agent or interop:Pilot
| Agent or Agent piloting an Application |
hasAccessNeed | AccessNeed | Link to an Access Need |
hasTrustedNeed | TrustedNeed | Link to a Trusted Need |
The AccessNeedGroupShape is used to validate an instance of the AccessNeedGroup class.
<#AccessNeedGroupShape> { a [ interop: AccessNeedGroup ] ; interop: accessNecessity [ interop: AccessRequired interop: AccessOptional ] ; interop: accessScenario [ interop: PersonalAccess interop: SharedAccess ] ; interop: authenticatesAs IRI; interop: hasAccessNeed IRI+; interop: hasAccessNeedOverride IRI*; interop: hasAccessDecoratorIndex IRI}
7.2.2. Access Need
An Access Need represents the requirement of one specific type of data represented by a shape tree, as part of an Access Need Group.
Each Access Need represents a request to access, create, or manage all or a subset of data in Data Registries and/or Remote Data Registries.
In a Data Registry, they can also request access to specific Data Instances associated with a Data Registration for a given shape tree if they have advance knowledge of their existence.
Shape trees provide both physical and virtual hierarchies. It is often the case that a shape tree which virtually references other shape trees will be assigned to an Access Need. The referenced shape trees can then be assigned to Referenced Access Needs that the Access Need links to.
Specific Data Instances may be requested by explicitly associating them with the Access Need via hasDataInstance.
Each Access Need has one or more access modes, and a property that
indicates the necessity of the Access Need; required or optional. For example, an Access Need for read access to shape tree N
can be identified as a required item in the Access Need Group.
Access Needs are described using language-specific Access Need Decorators.
AccessNeed | ||
---|---|---|
Property | Range | Description |
inAccessNeedGroup | AccessNeedGroup | Access Need Group that the Access Need is part of |
hasAccessNeedDecorator | AccessNeedDecorator | Decorator that explains the reason for the access need in the preferred language of the Agent |
registeredShapeTree | st:ShapeTree
| The shape tree requested by the Access Need |
hasShapeTreeDecorator | st:ShapeTreeDecorator
| Decorator associated with the shape tree that describes the name of the shape-tree and what data it represents in the preferred language of the Agent |
hasDataInstance | - | Request specific Data Instance of the registered shape tree. Requires advance knowledge of the Data Instance |
accessMode | acl:Read, acl:Write, acl:Control, acl:Append
| Requested modes of access for the Access Need |
accessNecessity | interop:AccessRequired , interop:AccessOptional
| Necessity of the access to the requesting party |
supportedBy | AccessNeed | An Access Need whose shape tree st:supports the shape tree of this Access Need
|
supports | AccessNeed | An Access Need that the shape tree of this Access Need st:supports
|
hasReferencedAccessNeed | ReferencedAccessNeed | Referenced Access Need linked to Access Need, whose shape tree st:references the shape tree associated
with the Referenced Access Need.
|
hasDataGrant | DataGrant | Data Grant associated with the Access Need, established when the Access Grant is created |
hasRemoteDataGrant | RemoteDataGrant | Remote Data Grant associated with the Access Need, established when the Access Grant is created |
The AccessNeedShape is used to validate an instance of the AccessNeed class.
<#AccessNeedShape> { a [ interop: AccessNeed ] ; interop: inAccessNeedGroup @<#:AccessNeedGroupShape> ; interop: registeredShapeTree IRI; interop: hasShapeTreeDecorator IRI; interop: hasAccessNeedDecorator IRI?; interop: hasDataInstance IRI*; interop: accessMode @<#:AccessModes> +; interop: accessNecessity [ interop: AccessRequired interop: AccessOptional ] ; interop: supportedBy IRI*; interop: supports IRI?; interop: hasReferencedAccessNeed @<#:ReferencedAccessNeedShape> *; interop: hasDataGrant @<#:DataGrantShape> ?; interop: hasRemoteGrant @<#:RemoteGrantShape> ?}
7.2.3. Referenced Access Need
A Referenced Access Need is linked directly to an Access Need,
and represents an access request for data represented by a shape tree that
is st:referenced
by the shape tree of the linked Access Need.
ReferencedAccessNeed | ||
---|---|---|
Property | Range | Description |
hasAccessNeed | AccessNeed | Access Need that the Referenced Access Need is linked to |
hasAccessNeedDecorator | AccessNeedDecorator | Decorator that explains the reason for the access need in the preferred language of the Agent |
registeredShapeTree | st:ShapeTree
| The shape tree requested by the Referenced Access Need |
hasShapeTreeDecorator | st:ShapeTreeDecorator
| Decorator associated with the shape tree that describes the name of the shape-tree and what data it represents in the preferred language of the Agent |
hasDataInstance | - | Request specific Data Instance of the registered shape tree. Requires advance knowledge of the Data Instance |
accessMode | acl:Read, acl:Write, acl:Control, acl:Append
| Requested modes of access for the Referenced Access Need |
accessNecessity | interop:AccessRequired , interop:AccessOptional
| Necessity of the access to the requesting party |
supportedBy | AccessNeed | An Access Need whose shape tree st:supports the shape tree of this Referenced Access Need
|
supports | AccessNeed | An Access Need that the shape tree of this Referenced Access Need st:supports
|
hasReferencedDataGrant | ReferencedDataGrant | Referenced Data Grant associated with the Referenced Access Need, established when the Access Grant is created |
hasReferencedRemoteDataGrant | ReferencedRemoteDataGrant | Referenced Remote Data Grant associated with the Referenced Access Need, established when the Access Grant is created |
The ReferencedAccessNeedShape is used to validate an instance of the ReferencedAccessNeed class.
<#ReferencedAccessNeedShape> { a [ interop: ReferencedAccessNeed ] ; interop: hasAccessNeed @<#:AccessNeedShape> ; interop: registeredShapeTree IRI; interop: hasShapeTreeDecorator IRI; interop: hasAccessNeedDecorator IRI?; interop: hasDataInstance IRI*; interop: accessMode @<#:AccessModes> +; interop: accessNecessity [ interop: AccessRequired interop: AccessOptional ] interop: supportedBy IRI*; # ? interop: supports IRI?; # ? interop: hasReferencedDataGrant @<#:DataGrantShape> ?; interop: hasReferencedRemoteGrant @<#:RemoteGrantShape> ?}
7.2.4. Trusted Need
A Trusted Need represents the request for elevated access to various types of top-level resources, including the Identity Profile Document, Registry Sets, or specific Registries.
Each Trusted Need has a single interop:trustedWithType
, which identifies
the type of trusted resource that is being requested.
Each Trusted Need has one or more access modes, and a property that
indicates the necessity of the Access Need; required or optional. For example, an Access Need for read access to shape tree N
can be identified as a required item in the Access Need Group.
Trusted Needs are described using language-specific Access Need Decorators.
TrustedNeed | ||
---|---|---|
Property | Range | Description |
inAccessNeedGroup | AccessNeedGroup | Access Need Group that the Trusted Need is part of |
trustedWithType | interop:Agent , interop:ApplicationRegistry interop:DataRegistry , interop:AccessGrantRegistry , interop:AccessReceiptRegistry , interop:RemoteDataRegistry
| Resource types that can be requested through a Trusted Need |
accessMode | acl:Read, acl:Write, acl:Control, acl:Append
| Requested modes of access for the Trusted Need |
accessNecessity | interop:AccessRequired , interop:AccessOptional
| Necessity of the access to the requesting party |
hasTrustedGrant | TrustedGrant | Trusted Grant associated with the Trusted Need, established when the Access Grant is created |
The TrustedNeedShape is used to validate an instance of the TrustedNeed class.
<#TrustedNeedShape> { a [ interop: TrustedNeed ] ; interop: inAccessNeedGroup IRI+; interop: hasAccessNeedDecorator IRI?; interop: trustedWith IRI*; interop: trustedWithType @<#:TrustedWithNeedTypes> ; interop: accessMode @<#:AccessModes> +; interop: accessNecessity [ interop: AccessRequired interop: AccessOptional ] ; interop: hasTrustedGrant @<#:TrustedGrantShape> ?} <#TrustedWithNeedTypes> [ interop: Agent interop: ApplicationRegistry interop: DataRegistry interop: AccessGrantRegistry interop: AccessReceiptRegistry interop: RemoteDataRegistry ]
7.2.5. Access Request
An Access Request is used to send Access Need Groups from one Agent to another.
AccessRequest | ||
---|---|---|
Property | Range | Description |
fromAgent | Agent | The Agent who sent the Access Request |
toAgent | Agent | The Agent the Access Request is meant for |
hasAccessNeedGroup | AccessNeedGroup | One or more Access Need Groups detailing the access requested |
The AccessRequestShape is used to validate an instance of the AccessRequest class.
<#AccessRequestShape> { a [ interop: AccessRequest ] ; interop: fromAgent IRI; # Agent who sent the receipt interop: toAgent IRI; # Recipient of the receipt interop: hasAccessNeedGroup @<#:AccessNeedGroupShape> +}
7.2.6. Access Decorator Index
An Access Decorator Index is a listing of one or more Access Decorator Series.
AccessDecoratorIndex | ||
---|---|---|
Property | Range | Description |
defaultLanguage | xsd:language
| Default language to select if not provided as input |
hasSeries | AccessDecoratorSeries | Link to an Access Decorator Series |
The AccessDecoratorIndexShape is used to validate an instance of the AccessDecoratorIndex class.
<#AccessDecoratorIndexShape> { a [ interop: AccessDecoratorIndex ] ; interop: defaultLanguage xsd: language ; interop: hasSeries @AccessDecoratorSeries+; }
7.2.6.1. Access Decorator Series
An Access Decorator Series has one or more Access Decorator Versions in a given language.
AccessDecoratorSeries | ||
---|---|---|
Property | Range | Description |
usesLanguage | xsd:language | Language code associated with the Access Decorator Series |
hasVersion | AccessDecoratorVersion | Links to an Access Decorator Version in the series |
The AccessDecoratorSeriesShape is used to validate an instance of the AccessDecoratorSeries class.
<#AccessDecoratorSeriesShape> { a [ interop: AccessDecoratorSeries ] ; interop: usesLanguage xsd: language ; interop: hasVersion @AccessDecoratorVersion+; }
7.2.6.2. Access Decorator Version
An Access Decorator Version is a versioned instance of a given Access Decorator Resource.
AccessDecoratorVersion | ||
---|---|---|
Property | Range | Description |
isVersion | xsd:string | Semantic version of the Access Decorator Resource (e.g. "1.1.0") |
hasSHA256 | xsd:string | SHA-256 hash of the linked Access Decorator Resource |
hasAccessDecoratorResource | AccessDecoratorResource | Links to the actual Access Decorator Resource document |
The AccessDecoratorVersionShape is used to validate an instance of the AccessDecoratorVersion class.
<#AccessDecoratorVersionShape> { a [ interop: AccessDecoratorVersion ] ; interop: isVersion xsd: string ; interop: hasSHA256 xsd: string ; interop: hasAccessDecoratorResource IRI; }
7.2.7. Access Decorator Resource
An Access Decorator Resource is a document that contains Access Need Group Decorators and Access Need Decorators in a given language.
AccessDecoratorResource | ||
---|---|---|
Property | Range | Description |
No properties | - | - |
7.2.7.1. Access Need Group Decorator
An Access Need Group Decorator provides a subject name and more in depth description that explains why a given Access Need Group is being requested of an Agent.
AccessNeedGroupDecorator | ||
---|---|---|
Property | Range | Description |
hasAccessNeedGroup | AccessNeedGroup | Access Need Group the decorator applies to |
skos:preflabel | xsd:string
| Short label (title) for the Access Need Group |
skos:definition | xsd:string
| Description of why the Access Need Group requires the access it is requesting. |
The AccessNeedGroupDecoratorShape is used to validate an instance of the AccessNeedGroupDecorator class.
<#AccessNeedGroupDecoratorShape> { a [ interop: AccessNeedGroupDecorator ] ; interop: hasAccessNeedGroup IRI; skos: prefLabel xsd: string ; skos: definition xsd: string }
7.2.7.2. Access Need Decorator
An Access Need Decorator provides a specific explanation of why that data type is being requested.
AccessNeedDecorator | ||
---|---|---|
Property | Range | Description |
hasAccessNeedGroup | AccessNeedGroup | Access Need Group the decorator applies to |
registeredShapeTree | st:ShapeTree
| Shape tree associated with the Access Need the decorator should apply to |
skos:prefLabel | xsd:string
| Specific explanation of why that data type is being requested |
The AccessNeedDecoratorShape is used to validate an instance of the AccessNeedDecorator class.
<#AccessNeedDecoratorShape> { a [ interop: AccessNeedDecorator ] ; interop: hasAccessNeedGroup IRI; interop: registeredShapeTree IRI; skos: prefLabel xsd: string }
7.3. Operations
7.3.1. Get Access Decorator Resource
Description | |||
---|---|---|---|
This operation returns the appropriate Access Decorator Resource from an input Access Decorator Index for the provided language.
If the provided language is not available, a default language is used instead.
Inputs
| | ||
INDEX
| An Access Decorator Index | ||
LANG
| The Agent’s preferred language
Outputs
| | |
Access Decorator Resource | Looked up in the Access Decorator Index, based on the Agent’s preferred language |
-
Let
USESERIES
beINDEX defaultSeries
-
Let
USEVERSION
be an unassigned Access Decorator Version -
For each Access Decorator Series
SERIES
inINDEX
-
Let
USESERIES
beSERIES
ifSERIES usesLanguage
==LANG
-
-
MUST return a status code of 404 if no Access Decorator Series are found.
-
For each Access Decorator Version
VERSION
inUSESERIES hasVersion
-
Let
USEVERSION
beVERSION
ifVERSION
is a more recent semantic version thanUSEVERSION
or ifUSEVERSION
is unassigned.
-
-
MUST return a status code of 404 if no Access Decorator Versions are found.
-
Let
DECR
be the Access Decorator Resource linked fromUSEVERSION hasAccessDecoratorResource
-
MUST return a status code of 404 if
DECR
is unassigned. -
return
DECR
7.3.2. Get Access Need Group Decorator
Description | |||
---|---|---|---|
This operation returns the appropriate Access Need Group Decorator for an input Access Need Group in the provided language. If the
provided language is not available, a default language is used instead.
Inputs
| | ||
GROUP
| An Access Need Group | ||
LANG
| The Agent’s preferred language
Outputs
| | |
Access Need Group Decorator | Associated with GROUP in LANG
|
-
Let
DECR
be the Access Decorator Resource returned by § 7.3.2 Get Access Need Group Decorator with inputs:GROUP hasAccessDecoratorIndex
,LANG
-
Let
USEGDEC
be an unassigned Access Need Group Decorator -
Let
GDECS
be all Access Need Group Decorators inDECR
-
For each [=Acces Need Group Decorator]
GDEC
inGDECS
-
Let
USEGDEC
beGDEC
ifGDEC hasAccessNeedGroup
isGROUP
-
MUST return a status code of 404 if
USEGDEC
is unassigned -
return
USEGDEC
7.3.3. Get Access Need Decorator
Description | |||
---|---|---|---|
This operation returns the appropriate Access Need Decorator for an input Access Need in the provided language. If the
provided language is not available, a default language is used instead.
Inputs
| | ||
NEED
| An Access Need | ||
LANG
| The Agent’s preferred language
Outputs
| | |
Access Need Decorator | Associated with NEED in LANG
|
-
Let
GROUP
beNEED inAccessNeedGroup
-
Let
DECR
be the Access Decorator Resource returned by § 7.3.2 Get Access Need Group Decorator with inputs:GROUP hasAccessDecoratorIndex
,LANG
-
Let
USENDEC
be an unassigned Access Need Decorator -
Let
NDECS
be all Access Need Decorators inDECR
-
For each [=Acces Need Decorator]
NDEC
inNDECS
-
Let
USENDEC
beNDEC
ifNDEC hasAccessNeedGroup
isGROUP
andNDEC registeredShapeTree
isNEED registeredShapeTree
-
MUST return a status code of 404 if
USENDEC
is unassigned -
return
USENDEC
8. Access Grants
8.1. Overview
Access Grants represent an Agent’s decision to grant access to some portion of the data in their control to another Agent. They provide the context needed to effectively manage permissions on a given Agent’s data through a compatible access control system.
There are two types of Access Grants:
-
Trusted Grants are made when a given Agent trusts another Agent with expanded, administrative-level privilege to the data in their control.
-
Data Grants are made when a given Agent wishes to share access to certain types or specific instances of data in their control.
Access Grants are recorded in an Agent’s Access Grant Registry.
Access Invitations represent Access Grants made to Agents with unknown or yet-to-be established identities.
8.2. Data Model
8.2.1. Summary
An Agent links to Access Grant Registry Sets via the interop:hasAccessGrantRegistrySet property.
An Access Grant Registry Set links to any number of Access Grant Registries via the interop:hasRegistry property.
An Access Grant Registry links to any number of registered Access Grants and Access Invitations via the interop:hasRegistration property.
8.2.2. Access Grant Registry Set
An Access Grant Registry Set is a Registry Set specifically made up of Access Grant Registries.
AccessGrantRegistrySet a rdfs:subClassOf RegistrySet | ||
---|---|---|
Property | Range | Description |
hasRegistry | Registry | Link to associated Access Grant Registries |
The AccessGrantRegistrySetShape is used to validate an instance of the AccessGrantRegistrySet class.
<#AccessGrantRegistrySetShape> { a [ interop: AccessGrantRegistrySet ] ; interop: hasRegistry IRI+}
The AccessGrantRegistrySetTree is assigned to a resource to ensure it will validate against the AccessGrantRegistrySetShape.
<#AccessGrantRegistrySetTree> a st: ShapeTree ; st: expectsType st: ShapeTreeResource ; st: validatedBy <interops#AccessGrantRegistrySetShape> .
8.2.3. Access Grant Registry
An Access Grant Registry is a collection of Access Grants stored in a specific location in a pod.
AccessGrantRegistry a rdfs:subClassOf Registry | ||
---|---|---|
Property | Range | Description |
hasRegistration | Registration | Link to associated Access Grants |
The AccessGrantRegistryShape is used to validate an instance of the AccessGrantRegistry class.
<#AccessGrantRegistryShape> { a [ interop: AccessGrantRegistry ] ; interop: hasRegistration IRI*}
The AccessGrantRegistryTree is assigned to a container resource to ensure that it will validate against the AccessGrantRegistryShape, and contain only conformant instances of the AccessGrantTree and AccessInvitationTree.
<#AccessGrantRegistryTree> a st: ShapeTree ; st: expectsType st: ShapeTreeContainer ; st: validatedBy <interops#AccessGrantRegistryShape> ; st: contains <#AccessGrantTree> , <#AccessInvitationTree> , st: AllowNone .
8.2.4. Access Grant
Each Access Grant represents access granted to an Access Grant Subject, based on access criteria detailed in one or more Access Need Groups.
Access may be granted to data in Data Registries through Data Grants.
Access may be granted to data in Remote Data Registries through Remote Data Grants.
Elevated access to registries, registry sets, or the identity of the Agent may be granted through Trusted Grants.
AccessGrant a rdfs:subClassOf Registration | ||
---|---|---|
Property | Range | Description |
registeredBy | Agent | Agent that registered the Access Grant |
registeredWith | Application | Application used to create the Access Grant |
registeredAt | xsd:dateTime | Date and time the Access Grant was created |
updatedAt | xsd:dateTime | Date and time the Access Grant was updated |
hasAccessGrantSubject | AccessGrantSubject | Links to the Access Grant Subject that was granted access. |
hasAccessNeedGroup | AccessNeedGroup | Links to an Access Need Group associated with the Access Grant. |
hasDataGrant | DataGrant | Links to a Data Grant associated with the Access Grant. |
hasTrustedGrant | TrustedGrant | Links to a Trusted Grant associated with the Access Grant. |
hasRemoteDataGrant | RemoteDataGrant | Links to a Remote Data Grant associated with the Access Grant. |
The AccessGrantShape is used to validate an instance of the AccessGrant class.
<#AccessGrantShape> { a [ interop: AccessGrant ] ; interop: registeredBy IRI; interop: registeredWith IRI?; interop: registeredAt xsd: dateTime ; interop: updatedAt xsd: dateTime ; interop: hasAccessGrantSubject @<#:AccessGrantSubject> ; interop: hasAccessNeedGroup @<#:AccessNeedGroupShape> +; ( interop: hasDataGrant @<#:DataGrantShape> + |interop: hasTrustedGrant @<#:TrustedGrantShape> + |interop: hasRemoteDataGrant @<#:RemoteDataGrantShape> +) ; }
The AccessGrantTree is assigned to a resource via the AccessGrantRegistryTree, and ensure that the assigned resource will validate against the AccessGrantShape.
<#AccessGrantTree> a st: ShapeTree ; st: expectsType st: ShapeTreeResource ; st: validatedBy <interops#AccessGrantShape> .
8.2.5. Access Grant Subject
An Access Grant Subject represents a unique combination of who and what is being granted access. For example, it allows a single Agent to be specified, or a given Agent using a given Application.
AccessGrantSubject | ||
---|---|---|
Property | Range | Description |
accessByAgent | Agent | Agent being granted access |
accessByApplication | Application | Application being granted access |
The AccessGrantSubjectShape is used to validate an instance of the AccessGrantSubject class.
<#AccessGrantSubjectShape> { a [ interop: AccessGrantSubject ] ; interop: accessGrantSubjectAgent IRI?; interop: accessGrantSubjectApplication IRI?}
8.2.6. Data Grant
A Data Grant records a decision made by an Agent to assign permissions for an Access Grant Subject to a Data Registration, in response to a given Access Need that was presented to them.
A Data Grant may have one or more Referenced Data Grants, when the shape tree associated via interop:registeredShapeTree
has one or
more Shape Tree References.
Each Data Grant has an assigned scope (interop:scopeOfGrant
), which
determines how permissions are assigned. The following types are
valid for a Data Grant:
-
interop:AllInstances
-
Applies to all Data Instances belonging to the associated Data Registration.
-
Permissions will be set for the Access Grant Subject on the Data Registration container, and will be inherited by all member Data Instances.
-
-
interop:SelectedInstances
-
Applies only to selected Data Instances belonging to the associated Data Registration, which are linked to the Data Grant via
interop:hasDataInstance
. -
Permissions will be set for the Access Grant Subject on each Data Instance.
-
-
interop:NoAccess
-
Indicates that no access is granted to the Access Grant Subject.
-
Applies to the entire Data Registration when there are no Data Instances linked via
interop:hasDataInstance
. -
When there are Data Instances linked via
interop:hasDataInstance
, this scope only applies to them.
-
When recording a Data Grant via § 8.4.8 Record Grant:
-
There must be an Access Need linked via
interop:satisfiesAccessNeed
that belongs to an Access Need Group linked to the same Access Grant. -
The Access Need must link back to the Data Grant via
interop:hasDataGrant
. -
Access Need and Data Grant must have the same
interop:accessModes
-
Access Need and Data Grant must have the same
interop:registeredShapeTree
DataGrant | ||
---|---|---|
Property | Range | Description |
hasAccessGrant | AccessGrant | Access Grant that the Data Grant belongs to |
satisfiesAccessNeed | AccessNeed | Links to the Access Need satisfied by the Data Grant |
registeredShapeTree | st:ShapeTree | Data Registration for the shape tree that access will be granted to |
hasDataRegistration | DataRegistration | Data Registration for registeredShapeTree that the Data Grant applies to |
accessMode | acl:Read, acl:Write, acl:Control, acl:Append | Modes of access granted to the target data at hasRegistration |
scopeOfGrant | interop:AllInstances, interop:SelectedInstances, interop:NoAccess |
Identifies the access scope of the Data Grant
|
hasDataInstance | Instance of registeredShapeTree | Links to a Data Instance of registeredShapeTree. |
hasReferencedDataGrant | ReferencedDataGrant | Links to a Referenced Data Grant when registeredShapeTree has references to other shape trees that should be included in authorization. |
The DataGrantShape is used to validate an instance of the DataGrant class.
<#DataGrantShape> { a [ interop: DataGrant ] ; interop: hasAccessGrant @<#:AccessGrantShape> ; interop: satisfiesAccessNeed @<#:AccessNeedShape> ; interop: registeredShapeTree IRI; interop: hasDataRegistration IRI; interop: accessMode @<#:AccessModes> +; interop: scopeOfGrant @<#:DataGrantScopes> ; interop: hasDataInstance IRI*; interop: hasReferencedDataGrant @<#:ReferencedDataGrantShape> }
The [DataGrantTree] ensures that the assigned resource will validate against the DataGrantShape.
<#DataGrantTree> a st: ShapeTree ; st: expectsType st: ShapeTreeResource ; st: validatedBy <interops:DataGrantShape> .
8.2.7. Referenced Data Grant
A Referenced Data Grant is linked from a Data Grant, and records a decision made by an Agent to assign permissions for an Access Grant Subject to a Data Registration, based on a Referenced Access Need that was presented to them. It stipulates that the shape tree of the Referenced Data Grant is effectively a "child" of the shape tree associated with the parent Data Grant that references it.
Like Data Grants, each Referenced Data Grant has an assigned
scope (interop:scopeOfGrant
), which
determines how permissions are assigned. The following types are
valid for a Referenced Data Grant:
-
interop:AllInstances
-
Applies to all Data Instances belonging to the associated Data Registration.
-
Permissions will be set for the Access Grant Subject on the Data Registration container, and will be inherited by all member Data Instances.
-
-
interop:InheritInstances
-
When the Data Grant linked via
interop:hasDataGrant
has a scope ofinterop:SelectedInstances
, and one or more Data Instances are selected, any Referenced Data Grants have the opportunity to narrow their own access scope to only include "child" Data Instances linked to the selected "parent" Data Instances. -
The link must follow the Shape Tree Reference between the parent Data Grant shape tree and the Referenced Data Grant shape tree.
-
Permissions are set conditionally for the Access Grant Subject, and have the benefit of applying to current and future Data Instances associated with a parent Data Instance.
-
-
interop:SelectedInstances
-
Applies only to selected Data Instances belonging to the associated Data Registration, which are linked to the Data Grant via
interop:hasDataInstance
. -
Permissions will be set for the Access Grant Subject on each Data Instance.
-
-
interop:NoAccess
-
Indicates that no access is granted to the Access Grant Subject.
-
Applies to the entire Data Registration when there are no Data Instances linked via
interop:hasDataInstance
. -
When there are Data Instances linked via
interop:hasDataInstance
, this scope only applies to them.
-
When recording a Referenced Data Grant via § 8.4.8 Record Grant:
-
There must be a Referenced Access Need linked via
interop:satisfiesAccessNeed
that belongs to an Access Need Group linked to the same Access Grant. -
The Referenced Access Need must link back to the Referenced Data Grant via
interop:hasReferencedDataGrant
. -
Referenced Access Need and Referenced Data Grant must have the same
interop:accessModes
-
Referenced Access Need and Referenced Data Grant must have the same
interop:registeredShapeTree
ReferencedDataGrant | ||
---|---|---|
Property | Range | Description |
hasDataGrant | DataGrant | Data Grant that the Referenced Data Grant belongs to |
satisfiesAccessNeed | ReferencedAccessNeed | Links to the Referenced Access Need satisfied by the Referenced Data Grant |
registeredShapeTree | st:ShapeTree | Data Registration for the shape tree that access will be granted to |
hasDataRegistration | DataRegistration | Data Registration for registeredShapeTree that the Referenced Data Grant applies to |
accessMode | acl:Read, acl:Write, acl:Control, acl:Append | Modes of access granted to the target data at hasRegistration |
scopeOfGrant | interop:AllInstances, interop:SelectedInstances, interop:InheritInstances, interop:NoAccess |
Identifies the access scope of the Data Grant
|
hasDataInstance | Instance of registeredShapeTree | Links to a Data Instance of registeredShapeTree. |
The ReferencedDataGrantShape is used to validate an instance of the ReferencedDataGrant class.
<#ReferencedDataGrantShape> { a [ interop: ReferencedDataGrant ] ; interop: hasDataGrant @<#:DataGrantShape> ; interop: satisfiesAccessNeed @<#:AccessNeedShape> ; interop: registeredShapeTree IRI; interop: hasDataRegistration IRI; interop: accessMode @<#:AccessModes> +; interop: scopeOfGrant @<#:DataGrantScopes> ; interop: hasDataInstance IRI*}
The [ReferencedDataGrantTree] ensures that the assigned resource will validate against the ReferencedDataGrantShape.
<#ReferencedDataGrantTree> a st: ShapeTree ; st: expectsType st: ShapeTreeResource ; st: validatedBy <interops:ReferencedDataGrantShape> .
8.2.8. Remote Data Grant
A Remote Data Grant records an authorization decision made by an Agent for an Access Grant Subject on a Remote Data Registration, in response to a given Access Need that was presented to them. This has the net effect of allowing the Access Grant Subject to see data that has been shared by other Agents.
A Remote Data Grant may have one or more Referenced Remote Data Grants,
when the shape tree associated via interop:registeredShapeTree
has one or
more Shape Tree References.
Each Remote Data Grant has an assigned scope (interop:scopeOfGrant
), which
determines how permissions are assigned. The following types are
valid for a Remote Data Grant:
-
interop:AllRemote
-
Applies to all Data Grants and Referenced Data Grants associated with all Remote Agent Data Registrations belonging to the associated Remote Data Registration.
-
Permissions will be set for the Access Grant Subject on the Remote Data Registration container, and will be inherited by all member Remote Agent Data Registrations, and the Data Grants and Referenced Data Grants contained by them.
-
-
interop:AllRemoteFromAgent
-
Applies to all Data Grants and Referenced Data Grants belonging to the selected Remote Agent Data Registrations linked via
interop:hasRemoteDataFromAgent
. -
Permissions will be set for the Access Grant Subject on the selected Remote Agent Data Registration containers, and will be inherited by all Data Grants and Referenced Data Grants contained by them.
-
-
interop:SelectedRemote
-
Applies only to selected Data Grants and/or Referenced Data Grants linked via
interop:hasDataGrant
,interop:hasReferencedDataGrant
. -
Permissions will be set for the Access Grant Subject on the selected Data Grant and/or Referenced Data Grant resources stored in Remote Agent Data Registrations.
-
-
interop:NoAccess
-
Indicates that no access is granted to the Access Grant Subject.
-
Applies to the entire Remote Data Registration when there are no Remote Agent Data Registrations linked via
interop:hasRemoteDataFromAgent
, and no Data Grants and/or Referenced Data Grants linked viainterop:hasDataGrant
,interop:hasReferencedDataGrant
. -
When there are linked Remote Agent Data Registrations, Data Grants, and/or Referenced Data Grants, this scope only applies to them.
-
When recording a Remote Data Grant via § 8.4.8 Record Grant:
-
There must be an Access Need linked via
interop:satisfiesAccessNeed
that belongs to an Access Need Group linked to the same Access Grant. -
The Access Need must link back to the Remote Data Grant via
interop:hasRemoteDataGrant
. -
Access Need and Remote Data Grant must have the same
interop:accessModes
-
Access Need and Remote Data Grant must have the same
interop:registeredShapeTree
RemoteDataGrant | ||
---|---|---|
Property | Range | Description |
hasAccessGrant | AccessGrant | Access Grant that the Remote Data Grant belongs to |
satisfiesAccessNeed | AccessNeed | Links to the Access Need satisfied by the Remote Data Grant |
registeredShapeTree | st:ShapeTree | The shape tree associated with the Remote Data Grant |
hasRemoteDataRegistration | RemoteDataRegistration | Remote Data Registration for registeredShapeTree
|
accessMode | acl:Read, acl:Write, acl:Control, acl:Append | Mode of access for the grant |
scopeOfGrant | interop:AllRemote, interop:AllRemoteFromAgent, interop:SelectedRemote, interop:NoAccess |
Identifies the access scope of the Remote Data Grant
|
hasRemoteDataFromAgent | RemoteAgentDataRegistration | Link to a Remote Agent Data Registration when
scope is AllRemoteFromAgent
|
hasDataGrant | DataGrant | Link to a Data Grant resource that was extracted from an Access Receipt and stored under the relevant Remote Agent Data Registration when the
scope is SelectedRemote
|
hasReferencedDataGrant | ReferencedDataGrant | Link to a Referenced Data Grant resource that was extracted from an Access Receipt and stored under the relevant Remote Agent Data Registration when the
scope is SelectedRemote
|
hasReferencedRemoteDataGrant | ReferencedRemoteDataGrant | Link to a Referenced Remote Data Grant when registeredShapeTree has references to other shape trees that
should be included in authorization
|
The RemoteDataGrantShape is used to validate an instance of the RemoteDataGrant class.
<#RemoteDataGrantShape> { a [ interop: RemoteDataGrant ] ; interop: hasAccessGrant @<#:AccessGrantShape> ; interop: satisfiesAccessNeed @<#:AccessNeedShape> +; interop: registeredShapeTree IRI; interop: hasRemoteDataRegistration IRI; interop: accessMode @<#:AccessModes> +; interop: scopeOfGrant @<#:RemoteDataGrantScopes> +; interop: hasRemoteDataFromAgent IRI*; interop: hasDataGrant IRI*; interop: hasReferencedDataGrant IRI*; interop: hasReferencedRemoteDataGrant @<#:ReferencedRemoteDataGrantShape> }
8.2.9. Referenced Remote Data Grant
A Referenced Remote Data Grant is linked from a Remote Data Grant, and records an authorization decision made by an Agent for an Access Grant Subject on a Remote Data Registration, based on a Referenced Access Need that was presented to them. It stipulates that the shape tree of the Referenced Remote Data Grant is effectively a "child" of the shape tree associated with the parent Remote Data Grant that references it.
Like Remote Data Grants, each Referenced Remote Data Grant has an assigned
scope (interop:scopeOfGrant
), which determines how permissions are assigned.
The following types are
valid for a Referenced Remote Data Grant:
-
interop:AllRemote
-
Applies to all Data Grants and Referenced Data Grants associated with all Remote Agent Data Registrations belonging to the associated Remote Data Registration.
-
Permissions will be set for the Access Grant Subject on the Remote Data Registration container, and will be inherited by all member Remote Agent Data Registrations, and the Data Grants and Referenced Data Grants contained by them.
-
-
interop:AllRemoteFromAgent
-
Applies to all Data Grants and Referenced Data Grants belonging to the selected Remote Agent Data Registrations linked via
interop:hasRemoteDataFromAgent
. -
Permissions will be set for the Access Grant Subject on the selected Remote Agent Data Registration containers, and will be inherited by all Data Grants and Referenced Data Grants contained by them.
-
-
interop:SelectedRemote
-
Applies only to selected Data Grants and/or Referenced Data Grants linked via
interop:hasDataGrant
,interop:hasReferencedDataGrant
. -
Permissions will be set for the Access Grant Subject on the selected Data Grant and/or Referenced Data Grant resources stored in Remote Agent Data Registrations.
-
-
interop:NoAccess
-
Indicates that no access is granted to the Access Grant Subject.
-
Applies to the entire Remote Data Registration when there are no Remote Agent Data Registrations linked via
interop:hasRemoteDataFromAgent
, and no Data Grants and/or Referenced Data Grants linked viainterop:hasDataGrant
,interop:hasReferencedDataGrant
. -
When there are linked Remote Agent Data Registrations, Data Grants, and/or Referenced Data Grants, this scope only applies to them.
-
When recording a Referenced Remote Data Grant via § 8.4.8 Record Grant:
-
There must be a Referenced Access Need linked via
interop:satisfiesAccessNeed
that belongs to an Access Need Group linked to the same Access Grant. -
The Referenced Access Need must link back to the Referenced Remote Data Grant via
interop:hasReferencedRemoteDataGrant
. -
Referenced Access Need and Referenced Remote Data Grant must have the same
interop:accessModes
-
Referenced Access Need and Referenced Remote Data Grant must have the same
interop:registeredShapeTree
ReferencedRemoteDataGrant | ||
---|---|---|
Property | Range | Description |
hasRemoteDataGrant | RemoteDataGrant | Remote Data Grant that the Referenced Remote Data Grant belongs to |
satisfiesAccessNeed | AccessNeed | Links to the Referenced Access Need satisfied by the Referenced Remote Data Grant |
registeredShapeTree | st:ShapeTree | The shape tree associated with the Referenced Remote Data Grant |
hasRemoteDataRegistration | RemoteDataRegistration | Remote Data Registration for registeredShapeTree
|
accessMode | acl:Read, acl:Write, acl:Control, acl:Append | Mode of access for the grant |
scopeOfGrant | interop:AllRemote, AllRemoteFromAgent, interop:SelectedRemote, interop:NoAccess |
Identifies the access scope of the Remote Data Grant
|
hasRemoteDataFromAgent | RemoteAgentDataRegistration | Link to a Remote Agent Data Registration when
scope is AllRemoteFromAgent
|
hasDataGrant | DataGrant | Link to a Data Grant resource that was extracted from an Access Receipt and stored under the relevant Remote Agent Data Registration when the
scope is SelectedRemote
|
hasReferencedDataGrant | ReferencedDataGrant | Link to a Referenced Data Grant resource that was extracted from an Access Receipt and stored under the relevant Remote Agent Data Registration when the
scope is SelectedRemote
|
The ReferencedRemoteDataGrantShape is used to validate an instance of the ReferencedRemoteDataGrant class.
<#ReferencedRemoteDataGrantShape> { a [ interop: ReferencedRemoteDataGrant ] ; interop: hasRemoteDataGrant @<#:RemoteDataGrantShape> ; interop: satisfiesAccessNeed @<#:AccessNeedShape> +; interop: registeredShapeTree IRI; interop: hasRemoteDataRegistration IRI; interop: accessMode @<#:AccessModes> +; interop: scopeOfGrant @<#:RemoteDataGrantScopes> +; interop: hasRemoteDataFromAgent IRI*; interop: hasDataGrant IRI*; interop: hasReferencedDataGrant IRI*}
8.2.10. Trusted Grant
A Trusted Grant records a decision made by a given Agent to trust another with elevated access to Registries, Registry Sets, or the Identity of the Agent themselves, based on a Trusted Need that was presented to them.
A Trusted Agent is an Agent that been granted elevated access through a Trusted Grant.
Each Trusted Grant represents accessed assigned to a trusted
resource identified by interop:trustedWith
, of a given type, indicated by interop:trustedWithType
.
Each Trusted Grant has an assigned scope (interop:scopeOfGrant
), which
determines how permissions are assigned. The following types are
valid for a Trusted Grant:
-
interop:TrustedAccess
- Applies to trusted resource linked viainterop:trustedWith
. Permissions will be set for the Access Grant Subject on the trusted resource. IftrustedWithType
is a type of Registry Set, the permissions will be applied to the Registry Set resource, as well as all of the Registries linked from that Registry Set. -
interop:NoAccess
- Indicates that no access is granted totrustedWith
. IftrustedWith
is a Registry Set, it indicates that no access is granted to the Registry Set resource, nor to the Registries linked from that Registry Set.
TrustedGrant | ||
---|---|---|
Property | Range | Description |
hasAccessGrant | AccessGrant | Access Grant that the Trusted Grant belongs to |
satisfiesTrustedNeed | TrustedNeed | Links to the Trusted Need satisfied by the Trusted Grant |
trustedWith | Agent, Registry Set, Registry |
Identifies the primary trusted resource of the Trusted Grant
|
trustedWithType |
| Specific type of instance linked via trustedWith
|
accessMode | acl:Read, acl:Write, acl:Control, acl:Append | Mode of access being granted to the instance linked via trustedWith
|
scopeOfGrant | interop:NoAccess, interop:TrustedAccess | Current scope of trusted access |
The TrustedGrantShape is used to validate an instance of the TrustedGrant class.
<#TrustedGrantShape> { a [ interop: TrustedGrant ] ; interop: hasAccessGrant @<#:AccessGrantShape> ; interop: satisfiesTrustedNeed @<#:TrustedNeedShape> +; interop: trustedWith IRI; interop: trustedWithType @<#:TrustedWithTypes> ; interop: accessMode @<#:AccessModes> +; interop: scopeOfGrant @<#:TrustedGrantScopes> +}
8.2.11. Access Invitation
An Access Invitation is a subclass of Access Grant used when an Agent wishes to grant access to another Agent whose decentralized identity is unknown to them, or may not exist yet, so they must be first invited through another channel (such as phone or email).
Like an Access Grant, an Access Invitation links to access criteria detailed in one or more Access Need Groups, with associated Data Grants or Trusted Grants indicating the intended access to be granted.
However, instead of linking to an Access Grant Subject, an Access Invitation links to one or more Access Invitation Channels.
Each channel represents a mechanism through which the invitation can be delivered and validated. The mechanism is designed so that multiple channels may be validated before an invitation is confirmed and converted to an Access Grant.
AccessInvitation a rdfs:subClassOf AccessGrant | ||
---|---|---|
Property | Range | Description |
registeredBy | Agent | Agent that registered the Access Invitation |
registeredWith | Application | Application used to create the Access Invitation |
registeredAt | xsd:dateTime | Date and time the Access Invitation was created |
updatedAt | xsd:dateTime | Date and time the Access Invitation was updated |
expiresAt | xsd:dateTime | Date and time the Access Invitation expires |
hasAccessInvitationChannel | AccessInvitationChannel | Links to an Access Invitation Channel |
hasAccessNeedGroup | AccessNeedGroup | Links to an Access Need Group associated with the Access Invitation. |
hasDataGrant | DataGrant | Links to a Data Grant associated with the Access Invitation. |
hasTrustedGrant | TrustedGrant | Links to a Trusted Grant associated with the Access Invitation. |
hasRemoteDataGrant | RemoteDataGrant | Links to a Remote Data Grant associated with the Access Invitation. |
The AccessInvitationShape is used to validate an instance of the AccessInvitation class.
<#AccessInvitationShape> { a [ interop: AccessInvitation ] ; interop: registeredBy IRI; interop: registeredWith IRI?; interop: registeredAt xsd: dateTime ; interop: updatedAt xsd: dateTime ; interop: expiresAt xsd: dateTime ?; interop: hasAccessNeedGroup @<#:AccessNeedGroupShape> +; ( interop: hasDataGrant @<#:DataGrantShape> + |interop: hasTrustedGrant @<#:TrustedGrantShape> + |interop: hasRemoteDataGrant @<#:RemoteDataGrantShape> +) ; interop: hasAccessInvitationChannel @<#:AccessInvitationChannelShape> +}
The AccessInvitationTree is assigned to a resource via the AccessGrantRegistryTree, and ensures that the assigned resource will validate against the AccessInvitationShape.
<#AccessInvitationTree> a st: ShapeTree ; st: expectsType st: ShapeTreeResource ; st: validatedBy <interops#AccessInvitationShape> .
8.2.12. Access Invitation Channel
An Access Invitation Channel represents a mechanism through which an Access Invitation can be delivered and validated.
AccessInvitationChannel | ||
---|---|---|
Property | Range | Description |
rdf:type | interop:PhoneInvitationChannel, interop:EmailInvitationChannel, interop:SMSInvitationChannel, interop:OfflineInvitationChannel, interop:LDNInvitationChannel | Each channel is represented by a subClassOf AccessInvitationChannel |
channelTarget | xsd:string | Target used when validating the channel |
channelCode | xsd:string | Code used for channel validation |
isValidated | xsd:boolean | Indicates whether the channel has been validated |
remainingAttempts | xsd:integer | Number of allowed validation attempts remaining |
The AccessInvitationChannelShape is used to validate an instance of the AccessInvitationChannel class.
<#AccessInvitationChannelShape> { a @<#ChannelTypes> ; interop: channelTarget xsd: string ; interop: channelCode xsd: string ; interop: isValidated xsd: boolean ; interop: remainingAttempts xsd: integer } <#ChannelTypes> [ : PhoneInvitationChannel # Telephone : EmailInvitationChannel : SMSInvitationChannel # SMS (Simple Messaging Service) : OfflineInvitationChannel # Other communication, e.g. verbal, shared note : LDNInvitationChannel # Linked Data Notification ]
8.3. Resource Hierarchy
Resource | Class | Shape | Shape Tree |
---|---|---|---|
/profile/
| - | - | ProfileTree |
-- grant#set
| AccessGrantRegistrySet | AccessGrantRegistrySetShape | AccessGrantRegistrySetTree |
/grants/#registry
| AccessGrantRegistry | AccessGrantRegistryShape | AccessGrantRegistryTree |
-- c482f931...630e5ab0#grant
| AccessGrant | AccessGrantShape | AccessGrantTree |
-- e0983a7e...88c387ea#grant
| AccessGrant | AccessGrantShape | AccessGrantTree |
-- eddf13d6...7f4962c5#grant
| AccessGrant | AccessGrantShape | AccessGrantTree |
-- a990c1b9...c041eb74#grant
| AccessGrant | AccessGrantShape | AccessGrantTree |
-- 265ef957...6689aee7#grant
| AccessGrant | AccessGrantShape | AccessGrantTree |
The Access Grant Registry Set and the Access Grant Registry MAY or MAY NOT be on the same pod.
Access Grant Registry Set and Access Grant Registry resources MAY use any resource or subject names.
Access Grants MUST use UUIDs for resource names.
8.4. Operations
Load or initialize the two main grant types: Access Grant, Access Invitation
-
§ 8.4.6 Load Grant - Load an existing Access Grant from an Access Grant Registry
-
§ 8.4.7 Load Invitation - Load an existing Access Invitation from an Access Grant Registry
-
§ 8.4.1 Initialize Grant - Initializes a new Access Grant for a given Access Grant Subject with one or more Access Need Groups
-
§ 8.4.2 Initialize Invitation - Initializes a new Access Invitation for one or more Access Invitation Channels with one or more Access Need Groups
Each Access Grant or Access Invitation will have some combination of Data Grants, Remote Data Grants, and/or Trusted Grants:
-
§ 8.4.3 Initialize Data Grant - Initialize a Data Grant as part of Access Grant initialization
-
§ 8.4.4 Initialize Remote Data Grant - Initialize a Remote Data Grant as part of Access Grant initialization
-
§ 8.4.5 Initialize Trusted Grant - Initialize a Trusted Grant as part of Access Grant initialization
Record Access Grants and Access Invitations:
-
§ 8.4.8 Record Grant - Store a new or updated Access Grant in an Access Grant Registry
-
§ 8.4.9 Record Invitation - Store a new or updated Access Invitation in an Access Grant Registry
Apply permissions based on the composition of an Access Grant:
-
§ 8.4.12 Apply Permissions - Apply permissions for an input Access Grant
-
§ 8.4.13 Apply Data Permissions - Apply permissions for Data Grants
-
§ 8.4.14 Apply Data Registration Permissions - Apply permissions for a Data Registration
-
§ 8.4.16 Apply Remote Data Permissions - Apply permissions for Remote Data Grants
-
§ 8.4.17 Apply Remote Data Registration Permissions - Apply permissions for a given Remote Data Registration
-
§ 8.4.18 Apply Trusted Permissions - Apply permissions for Trusted Grants
-
§ 8.4.19 Apply Resource Permissions - Apply permissions on a given resource for a given Access Grant Subject
-
§ 8.4.20 Apply Conditional Resource Permissions - Apply permissions on a given resource for a given Access Grant Subject, condiioned upon a graph relationship
-
§ 8.4.21 Remove Resource Permissions - Remove permissions on a given resource for a given Access Grant Subject
-
8.4.1. Initialize Grant
Description | |||
---|---|---|---|
Initialize an Access Grant by processing
the input Access Need Groups and
then initializing Data Grants, Remote Data Grants,
and/or Trusted Grants with no access (yet).
Inputs
| | ||
SUBJECT
| The Access Grant Subject that the Access Grant is related to | ||
GROUPS
| Access Need Groups to associate with the Access Grant | ||
LANG
| The Agent’s preferred language
Outputs
| | |
Access Grant | Newly initialized for the Access Grant Subject |
-
Let
GRANT
be a newly initialized Access Grant -
Let
GRANT hasAccessGrantSubject
beSUBJECT
-
For each Access Need Group
GROUP
inGROUPS
-
Link
GROUP
toGRANT
viaGRANT hasAccessNeedGroup
-
-
For each Access Need Group
GROUP
linked viaGRANT hasAccessNeedGroup
-
For each Access Need
NEED
inGROUP
-
Call § 8.4.3 Initialize Data Grant with inputs:
NEED
-
Call § 8.4.4 Initialize Remote Data Grant with inputs:
NEED
-
-
For each Trusted Need
TNEED
inGROUP
-
Call § 8.4.5 Initialize Trusted Grant with inputs:
TNEED
-
-
-
Return
GRANT
8.4.2. Initialize Invitation
Description | |||
---|---|---|---|
Initialize an Access Invitation by processing
the input Access Need Groups and
then initializing Data Grants, Remote Data Grants,
or Trusted Grants with no access (yet).
Inputs
| | ||
ICHANNELS
| A set of Access Invitation Channels | ||
GROUPS
| Access Need Groups to associate with the Access Invitation | ||
LANG
| The Agent’s preferred language
Outputs
| | |
Access Invitation | Newly initialized based on input Access Invitation Channels |
-
Let
INVITE
be a newly initialized Access Invitation -
For each Access Invitation Channel
ICHANNEL
inICHANNELS
-
Let
ICHANNEL
be linked toINVITE
viaINVITE hasAccessInvitationChannel
-
-
For each Access Need Group
GROUP
inGROUPS
-
Link
GROUP
toINVITE
viaINVITE hasAccessNeedGroup
-
-
For each Access Need Group
GROUP
linked viaINVITE hasAccessNeedGroup
-
For each Access Need
NEED
inGROUP
-
Call § 8.4.3 Initialize Data Grant with inputs:
NEED
,GRANT
-
Call § 8.4.4 Initialize Remote Data Grant with inputs:
NEED
,GRANT
-
-
For each Trusted Need
TNEED
inGROUP
-
Call § 8.4.5 Initialize Trusted Grant with inputs:
TNEED
,GRANT
-
-
-
Return
INVITE
8.4.3. Initialize Data Grant
Description | |||
---|---|---|---|
Initialize a Data Grant and link it to the provided Access Need NEED .
Initialize Referenced Data Grants if the Access Need Inputs
| | ||
NEED
| An Access Need | ||
GRANT
| Access Grant that the Data Grant will be linked to
Outputs
| | |
Data Grant | Initialized Data Grant corresponding to NEED
|
-
Let
DG
be a newly initialized Data Grant -
Let
DG hasAccessGrant
beGRANT
-
Let
DG satisfiesAccessNeed
beNEED
-
Let
DG registeredShapeTree
beNEED registeredShapeTree
-
Let
DG hasRegistration
be a Data RegistrationDR
whereDR registeredShapeTree
==DG registeredShapeTree
-
Let
DG accessmode
s beCACCESS accessmode
s -
Let
DG scopeOGrant
beinterop:NoAccess
-
Let
NEED hasDataGrant
beDG
-
For each Referenced Access Need
REFNEED
linked viaNEED hasReferencedAccessNeed
-
Let
REFDG
be a newly initialized Referenced Data Grant -
Let
REFDG hasDataGrant
beDG
-
Let
REFDG satisfiesAccessNeed
beREFNEED
-
Let
REFDG registeredShapeTree
beREFNEED registeredShapeTree
-
Let
REFDG hasRegistration
be a Data RegistrationDR
whereDR registeredShapeTree
==REFDG registeredShapeTree
-
Let
REFDG accessMode
s beREFNEED accessMode
s -
Let
REFDG scopeOfGrant
beinterop:NoAccess
-
Link
REFDG
toDG
viaDG hasReferencedDataGrant
-
-
Return
DG
8.4.4. Initialize Remote Data Grant
Description | |||
---|---|---|---|
Initialize a Remote Data Grant and link it to the provided Access Need NEED .
Initialize Referenced Remote Data Grants if the Access Need Inputs
| | ||
NEED
| An Access Need | ||
GRANT
| Access Grant that the Remote Data Grant will be linked to
Outputs
| | |
Remote Data Grant | Initialized Remote Data Grant corresponding to NEED
|
-
Let
RDG
be a newly initialized Remote Data Grant -
Let
RDG hasAccessGrant
beGRANT
-
Let
RDG satisfiesAccessNeed
beNEED
-
Let
RDG registeredShapeTree
beNEED registeredShapeTree
-
Let
RDG accessmode
s beNEED accessmode
s -
Let
RDG scopeOfGrant
beinterop:NoAccess
-
Let
NEED hasRemoteDataGrant
beRDG
-
For each Referenced Access Need
REFNEED
linked viaNEED hasReferencedAccessNeed
-
Let
REFRDG
be a newly initialized Referenced Remote Data Grant -
Let
REFRDG hasRemoteDataGrant
beRDG
-
Let
REFRDG satisfiesAccessNeed
beREFNEED
-
Let
REFRDG registeredShapeTree
beREFNEED registeredShapeTree
-
Let
REFRDG hasRegistration
be a Data RegistrationDR
whereDR registeredShapeTree
==REFRDG registeredShapeTree
-
Let
REFRDG accessMode
s beREFNEED accessMode
s -
Let
REFRDG scopeOfGrant
beinterop:NoAccess
-
Link
REFRDG
toRDG
viaRDG hasReferencedRemoteDataGrant
-
-
Return
RDG
8.4.5. Initialize Trusted Grant
Description | |||
---|---|---|---|
Initialize a Trusted Grant and link it to the provided Trusted Need TNEED .
Inputs
| | ||
TNEED
| A Trusted Need | ||
GRANT
| Access Grant that the Trusted Grant will be linked to
Outputs
| | |
Trusted Grant | Initialized Trusted Grant corresponding to TNEED
|
-
Let
TG
be a newly initialized Trusted Grant -
Let
TG hasAccessGrant
beGRANT
-
Let
TG satisfiesTrustedNeed
beTNEED
-
Let
TG trustedWith
beinterop:NoAccess
-
Let
TG scopeOfGrant
beinterop:NoAccess
-
Let
TG trustedWithType
beTNEED trustedWithType
-
Let
TG accessmode
s beTNEED accessmode
s -
Let
TNEED hasTrustedGrant
beTG
-
Return
TG
8.4.6. Load Grant
Description | |||
---|---|---|---|
This operation will load an Access Grant from a given Access Grant Registry
Inputs
| | ||
SUBJECT
| An Access Grant Subject to lookup | ||
REGISTRY
| An Access Grant Registry to search
Outputs
| | |
Access Grant | Corresponding to SUBJECT
|
-
For each Access Grant
GRANT
included inREGISTRY hasRegistration
-
return
GRANT
ifGRANT hasAccessGrantSubject
==SUBJECT
-
8.4.7. Load Invitation
Description | |||
---|---|---|---|
This operation will load an Access Invitation from a
given Access Grant Registry
Inputs
| | ||
TARGET
| An interop:ChannelTarget to match
| ||
CODE
| An optional interop:channelCode to match
| ||
REGISTRY
| An Access Grant Registry to search
Outputs
| | |
Access Invitations | Matching TARGET and (if provided) CODE
|
-
Let
INVITATIONS
be an empty set of Access Invitations -
For each Access Invitation
INVITATION
linked viaREGISTRY hasRegistration
-
For each Access Invitation Channel
ICHANNEL
linked viaINVITATION hasAccessInvitationChannel
-
Next if
ICHANNEL channelTarget
!=TARGET
-
Next if
CODE
is not empty andICHANNEL channelCode
!=CODE
-
Add
INVITATION
toINVITATIONS
-
-
-
Return
INVITATIONS
8.4.8. Record Grant
Description | |||
---|---|---|---|
This operation stores a new or updated Access Grant in
an Access Grant Registry, applies permissions accordingly, and
calls for an Access Receipt to be provided.
Inputs
| | ||
GRANT
| An Access Grant to store in REGISTRY
| ||
REGISTRY
| The Access Grant Registry to store GRANT into
Outputs
| | |
Access Grant | Stored in REGISTRY with permissions applied and Access Receipt furnished
|
-
Add or Update
GRANT
resource in theREGISTRY
container, conforming to the assigned interopt:AccessGrantTree. -
Link
GRANT
to theREGISTRY
viaREGISTRY hasRegistration
if it has not already been added -
Call § 8.4.12 Apply Permissions with inputs:
GRANT
-
Call § 9.4.1 Provide Access Receipt with inputs:
GRANT
-
Return
GRANT
Need to properly factor in multi-pod scenarios. Must identify the proper access registry to store things in based on the data registration, which means pods will also need to be registered.
8.4.9. Record Invitation
Description | |||
---|---|---|---|
This operation stores a new or updated Access Invitation in
an Access Grant Registry.
Inputs
| | ||
INVITATION
| An Access Invitation | ||
REGISTRY
| An Access Grant Registry
Outputs
| | |
Access Invitation | Stored in REGISTRY
|
-
Add or Update
INVITATION
resource in theREGISTRY
container, conforming to the assigned interopt:AccessInvitationTree -
Link
INVITATION
to theREGISTRY
viaACCESS hasRegistration
if it has not already been added -
Call § 8.4.10 Deliver Invitation with inputs:
INVITATION
-
Return
INVITATION
8.4.10. Deliver Invitation
Write standard operation for invitation delivery
8.4.11. Validate Invitation
Write standard operation for validating an invitation
8.4.12. Apply Permissions
Description | |||
---|---|---|---|
This operation takes a validated Access Grant GRANT associated with a given Access Grant Subject and
applies the permissions accordingly based on the Data Grants, Remote Data Grants, and/or Trusted Grants associated with the Access Grant. It applies to both new and updated Access Grants.
Inputs
| | ||
GRANT
| The Access Grant to apply permissions for
Outputs
| | |
Access Grant | That has had the relevant permissions applied |
-
Call § 8.4.13 Apply Data Permissions with inputs:
GRANT
-
Call § 8.4.16 Apply Remote Data Permissions with inputs:
GRANT
-
Call § 8.4.18 Apply Trusted Permissions with inputs:
GRANT
-
Return
GRANT
8.4.13. Apply Data Permissions
Description | |||
---|---|---|---|
This operation applies data permissions for a new or updated Access Grant.
It iterates over each Data Grant linked via All Data Grants and Referenced Data Grants are added to
a hash map The end result is the keys of Each Data Registration and the array of grants that affect it are then passed to § 8.4.14 Apply Data Registration Permissions. Inputs
| | ||
GRANT
| Access Grant to apply permissions for
Outputs
| | |
Access Grant | That has had the relevant permissions applied |
-
Let
DRHASH
be an empty hash map where a Data Registration is key and the value is an array of Data Grants and/or Referenced Data Grants. -
For each Data Grant
DG
linked viaGRANT hasDataGrant
-
Let
DRKEY
beDG hasDataRegistration
added or found inDRHASH
-
Add
DG
to the value array forDRKEY
if missing -
For each Referenced Data Grant
REFDG
linked viaDG hasReferencedDataGrant
-
Let
REFDRKEY
beREFDG hasDataRegistration
added or found inDRHASH
-
Add
REFDG
to the array forREFDRKEY
if missing
-
-
-
For each Data Registration
DR
inDRHASH
-
Call § 8.4.14 Apply Data Registration Permissions with inputs:
DR
,DRHASH[DR]
,GRANT
-
-
Return
GRANT
8.4.14. Apply Data Registration Permissions
Description | |||
---|---|---|---|
This operation applies permissions for a given Data Registration, based on the Data Grants that have been assigned to it from the input Access Grant. Before assigning permissions, any existing permissions for the Access Grant Subject are cleared. This operation does a full scan for simplicity, but optimization is recommended. All of the grants are iterated, and organized into a hash map
with data-specific
Inputs
| | ||
DR
| A Data Registration | ||
DATAGRANTS
| An array of Data Grants and Referenced Data Grants associated with the Data Registration in GRANT
| ||
GRANT
| Access Grant that permissions are being applied for
Outputs
| | |
Data Registration | That has had the relevant permissions applied |
-
Let
SUBJECT
be the Access Grant Subject linked viaGRANT hasAccessGrantSubject
-
Call § 8.4.21 Remove Resource Permissions with inputs:
DR
,SUBJECT
-
For each Data Instance
DI
linked viaDR ldp:hasMember
-
Call § 8.4.21 Remove Resource Permissions with inputs:
DI
,SUBJECT
-
-
Let
SCOPEHASH
be a hash map with keys:interop:AllInstances
,interop:SelectedInstances
,interop:InheritInstances
,interop:NoAccess
-
Let
SCOPEHASH[interop:SelectedInstances]
be an empty hash map where Data Instances are keys with an array ofinterop:AccessMode
s as values -
Let
SCOPEHASH[interop:InheritInstances]
be an empty hash map where parent Data Instances are keys with an array ofinterop:AccessMode
s as values -
For each Data Grant or Referenced Data Grant
DATAGRANT
inDATAGRANTS
-
If
DATAGRANT scopeOfGrant
isinterop:AllInstances
-
Let
SCOPEHASH[interop:AllInstances]
value be a union of current access modes andDATAGRANT accessMode
s
-
-
If
DATAGRANT scopeOfGrant
isinterop:NoAccess
-
Let
SCOPEHASH[interop:NoAccess]
value betrue
-
-
If
DATAGRANT scopeOfGrant
isinterop:SelectedInstances
-
For each Data Instance
DI
linked viaDATAGRANT hasDataInstance
-
Let
INSTKEY
be Data InstanceDI
added or found inSCOPEHASH[interop:SelectedInstances][DI]
-
Let
SCOPEHASH[interop:SelectedInstances][DI]
value be a union of current access modes andDATAGRANT accessMode
s
-
-
-
If
DATAGRANT scopeOfGrant
isinterop:InheritInstances
-
Let
PDG
be the parent Data Grant linked viaDATAGRANT hasDataGrant
that the Referenced Data Grant inherits from. -
Error if
PDG scopeOfGrant
is notinterop:SelectedInstances
-
For each Data Instance
DI
linked viaPDG hasDataInstance
-
Let
INSTKEY
be Data InstanceDI
added or found inSCOPEHASH[interop:InheritInstances][DI]
-
Let
SCOPEHASH[interop:InheritInstances][DI]
value be a union of current access modes andDATAGRANT accessMode
s
-
-
-
-
If
SCOPEHASH[interop:AllInstances]
is not empty-
Call § 8.4.19 Apply Resource Permissions with inputs:
DR
,SUBJECT
,MODES
-
-
If
SCOPEHASH[interop:InheritInstances]
is not empty-
For each Data Instance
DI
inSCOPEHASH[interop:InheritInstances]
-
Let
REF
be the Shape Tree Reference from calling § 8.4.15 Get Shape Tree Reference with inputs:DR registeredShapeTree
,DI registeredShapeTree
-
Let
PRED
be the rdf:property extracted fromREF traverseViaShapePath
-
Call § 8.4.20 Apply Conditional Resource Permissions with inputs:
DR
,SUBJECT
,MODES
,DI
,PRED
,NULL
-
-
If
SCOPEHASH[interop:SelectedInstances]
is not empty-
For each Data Instance
DI
inSCOPEHASH[interop:SelectedInstances]
-
Call § 8.4.19 Apply Resource Permissions with inputs:
SCOPEHASH[interop:SelectedInstances][DI]
,SUBJECT
,MODES
-
-
8.4.15. Get Shape Tree Reference
Description | |||
---|---|---|---|
This option will return a Shape Tree Reference between
a shape tree REFERENCED and a shape tree REFERENCEDBY
Inputs
| | ||
REFERENCED
| The referenced shape tree | ||
REFERENCEDBY
| The shape tree that REFERENCED is referenced by
Outputs
| | |
Shape Tree Reference | Linking REFERENCEDBY to REFERENCED
|
-
For each Shape Tree Reference
REF
linked viaREFERENCEDBY st:references
-
Return
REF
ifREF hasShapeTree
isREFERENCED
-
-
Error because no Shape Tree Reference was found for
REFERENCED
8.4.16. Apply Remote Data Permissions
Description | |||
---|---|---|---|
This operation applies remote data permissions for a new or updated Access Grant.
It iterates over each Remote Data Grant linked via All Remote Data Grants and Referenced Remote Data Grants are added to
a hash map The end result is the keys of Each Remote Data Registration and the array of grants that affect it are then passed to § 8.4.17 Apply Remote Data Registration Permissions. Inputs
| | ||
GRANT
| Access Grant to apply permissions for
Outputs
| | |
Access Grant | That has had the relevant permissions applied |
-
Let
RDRHASH
be an empty hash map where a Remote Data Registration is key and the value is an array of Remote Data Grants and/or Referenced Remote Data Grants. -
For each Remote Data Grant
RDG
linked viaGRANT hasRemoteDataGrant
-
Let
RDRKEY
beRDG hasRemoteDataRegistration
added or found inRDRHASH
-
Add
RDG
to the value array forRDRKEY
if missing -
For each Referenced Remote Data Grant
REFRDG
linked viaRDG hasReferencedRemoteDataGrant
-
Let
REFRDRKEY
beREFRDG hasRemoteDataRegistration
added or found inRDRHASH
-
Add
REFRDG
to the array forREFRDRKEY
if missing
-
-
-
For each Remote Data Registration
RDR
inRDRHASH
-
Call § 8.4.17 Apply Remote Data Registration Permissions with inputs:
RDR
,RDRHASH[RDR]
,GRANT
-
-
Return
GRANT
8.4.17. Apply Remote Data Registration Permissions
Description | |||
---|---|---|---|
This operation applies permissions for a given Remote Data Registration, based on the Remote Data Grants that have been assigned to it from the input Access Grant. Before assigning permissions, any existing permissions for the Access Grant Subject are cleared. This operation does a full scan for simplicity, but optimization is recommended. All of the grants are iterated, and organized into a hash map
with data-specific
Inputs
| | ||
RDR
| A Remote Data Registration | ||
REMOTEGRANTS
| An array of Remote Data Grants and Referenced Remote Data Grants associated with the Data Registration in GRANT
| ||
GRANT
| Access Grant that permissions are being applied for
Outputs
| | |
Remote Data Registration | That has had the relevant permissions applied |
-
Let
SUBJECT
be the Access Grant Subject linked viaGRANT hasAccessGrantSubject
-
Call § 8.4.21 Remove Resource Permissions with inputs:
RDR
,SUBJECT
-
For each Remote Agent Data Registration
RADR
linked viaRDR hasRemoteAgentDataRegistration
-
Call § 8.4.21 Remove Resource Permissions with inputs:
RADR
,SUBJECT
-
For each Data Grant or Referenced Data Grant
DATAGRANT
linked viaRADR satisfiesDataGrant
-
Call § 8.4.21 Remove Resource Permissions with inputs:
DATAGRANT
,SUBJECT
-
-
-
Let
SCOPEHASH
be a hash map with keys:interop:AllRemote
,interop:AllRemoteFromAgent
,interop:SelectedRemote
,interop:NoAccess
-
Let
SCOPEHASH[interop:AllRemoteFromAgent]
be an empty hash map where Remote Agent Data Registrations are keys with an array ofinterop:AccessMode
s as values -
Let
SCOPEHASH[interop:SelectedRemote]
be an empty hash map where selected Data Grants or Referenced Data Grants are keys with an array ofinterop:AccessMode
s as values -
For each Remote Data Grant or Referenced Remote Data Grant
REMOTEGRANT
inREMOTEGRANTS
-
If
REMOTEGRANT scopeOfGrant
isinterop:AllRemote
-
Let
SCOPEHASH[interop:AllRemote]
value be a union of currentinterop:accessMode
s andREMOTEGRANT accessMode
s
-
-
If
REMOTEGRANT scopeOfGrant
isinterop:NoAccess
-
Let
SCOPEHASH[interop:NoAccess]
value betrue
-
-
If
REMOTEGRANT scopeOfGrant
isinterop:AllRemoteFromAgent
-
For each Remote Agent Data Registration
RADR
linked viaREMOTEGRANT hasRemoteAgentDataRegistration
-
Let
RADRKEY
be Remote Agent Data RegistrationRADR
added or found inSCOPEHASH[interop:AllRemoteFromAgent][RADR]
-
Let
SCOPEHASH[interop:AllRemoteFromAgent][RADR]
value be a union of currentinterop:accessMode
s andREMOTEGRANT accessMode
s
-
-
-
If
REMOTEGRANT scopeOfGrant
isinterop:SelectedRemote
-
For each Data Grant or Referenced Data Grant
DATAGRANT
linked viaREMOTEGRANT hasDataGrant
orREMOTEGRANT hasReferencedDataGrant
-
Let
GRANTKEY
beDATAGRANT
added or found inSCOPEHASH[interop:SelectedRemote][DATAGRANT]
-
Let
SCOPEHASH[interop:SelectedRemote][DATAGRANT]
value be a union of currentinterop:accessMode
s andREMOTEGRANT accessMode
s
-
-
-
-
If
SCOPEHASH[interop:AllRemote]
is not empty-
Call § 8.4.19 Apply Resource Permissions with inputs:
RDR
,SUBJECT
,MODES
-
-
If
SCOPEHASH[interop:AllRemoteFromAgent]
is not empty-
For each Remote Agent Data Registration
RADR
inSCOPEHASH[interop:AllRemoteFromAgent]
-
Call § 8.4.19 Apply Resource Permissions with inputs:
SCOPEHASH[interop:AllRemoteFromAgent][RADR]
,SUBJECT
,MODES
-
-
-
If
SCOPEHASH[interop:SelectedRemote]
is not empty-
For each Data Grant or Referenced Data Grant
DATAGRANT
inSCOPEHASH[interop:SelectedRemote]
-
Call § 8.4.19 Apply Resource Permissions with inputs:
SCOPEHASH[interop:SelectedRemote][DATAGRANT]
,SUBJECT
,MODES
-
-
8.4.18. Apply Trusted Permissions
Description | |||
---|---|---|---|
This operation applies permissions for a given Trusted Grant. It applies
to both new and updated Trusted Grants.
Inputs
| | ||
TGRANT
| A validated Trusted Grant | ||
GRANT
| The validated Access Grant that TGRANT belongs to
Outputs
| | |
Trusted Grant | That has had the relevant permissions applied |
-
Let
SUBJECT
be the Access Grant SubjectGRANT hasAccessGrantSubject
-
For each Trusted Grant
TGRANT
linked viaGRANT hasTrustedGrant
-
Let
MODES
be the access modes linked viaTGRANT accessMode
-
If
TGRANT trustedWithType
isinterop:Agent
-
Let
PROFILE
beTGRANT trustedWith
-
Call § 8.4.19 Apply Resource Permissions with inputs:
PROFILE
,SUBJECT
,MODES
-
-
If
TGRANT trustedWithType
isinterop:RegistrySet
-
Let
SET
beTGRANT trustedWith
-
Let
REGISTRIES
be the Registries linked viaSET hasRegistry
-
Call § 8.4.19 Apply Resource Permissions with inputs:
SET
,SUBJECT
,MODES
-
For each Registry
REGISTRY
inREGISTRIES
-
Call § 8.4.19 Apply Resource Permissions with inputs:
REGISTRY
,SUBJECT
,MODES
-
-
-
If
TGRANT trustedWithType
isinterop:Registry
-
Let
REGISTRY
beTGRANT trustedWith
-
Call § 8.4.19 Apply Resource Permissions with inputs:
REGISTRY
,SUBJECT
,MODES
-
-
8.4.19. Apply Resource Permissions
Description | |||
---|---|---|---|
This operation applies permissions on a given resource for a given Access Grant Subject. It clears any existing permissions for
the Access Grant Subject first, so that the resultant permissions
are exactly the ones requested.
Inputs
| | ||
RESOURCE
| Resource whose permissions will be changed | ||
SUBJECT
| The Access Grant Subject who the permissions apply to | ||
MODES
| A list of access modes to apply to the resource
Outputs
| | |
Boolean | Success or Failure |
-
Call § 8.4.21 Remove Resource Permissions with inputs:
RESOURCE
,SUBJECT
-
Add a new Authorization Statement
NEWSTATEMENT
toACL
-
Set
NEWSTATEMENT
Access Grant Subject toSUBJECT
. -
Set the access modes for
NEWSTATEMENT
toMODES
-
If
RESOURCE
is a container-
Set all members of
RESOURCE
to inherit the same permissions
-
8.4.20. Apply Conditional Resource Permissions
Description | |||
---|---|---|---|
This operation applies permissions on a given resource for a given Access Grant Subject. Those permissions are conditioned upon the
existence of a graph link between a node in the resource and another node
in another resource on the same pod.
It clears any existing permissions for the Access Grant Subject first, so that the resultant permissions are exactly the ones requested. Inputs
| | ||
RESOURCE
| Resource whose permissions will be changed | ||
SUBJECT
| The Access Grant Subject who the permissions apply to | ||
MODES
| A list of access modes to apply to the resource | ||
CONDSUB
| Subject of conditional link | ||
CONDPRED
| Predicate for conditional link | ||
CONDOBJ
| Object for conditional link
Outputs
| | |
Boolean | Success or Failure |
Need to determine how to deal with objects that are dynamic, where we need to match against more than one resource and the subject identifier could? vary
-
Call § 8.4.21 Remove Resource Permissions with inputs:
RESOURCE
,SUBJECT
-
Add a new Authorization Statement
NEWSTATEMENT
toACL
-
Set
NEWSTATEMENT
Access Grant Subject toSUBJECT
-
Set a condition on
NEWSTATEMENT
that access is only permitted when a graph link is present composed of subject:CONDSUB
, predicate:CONDPRED
, object:CONDOBJ
-
Set the access modes for
NEWSTATEMENT
toMODES
-
If
RESOURCE
is a container-
Set all members of
RESOURCE
to inherit the same permissions
-
8.4.21. Remove Resource Permissions
Description | |||
---|---|---|---|
This operation removes permissions on a given resource for a given Access Grant Subject.
Inputs
| | ||
RESOURCE
| Resource whose permissions will be changed | ||
SUBJECT
| The Access Grant Subject who the permissions apply to
Outputs
| | |
Boolean | Success or Failure |
-
Let
ACL
be the ACL Resource directly associated withRESOURCE
-
Let
STATEMENTS
be any Authorization Statements inACL
directly associated withSUBJECT
. -
For each
STATEMENT
inSTATEMENTS
-
Remove Access Grant Subject from
STATEMENT
-
Remove
STATEMENT
if there are no remaining Access Grant Subjects
-
8.4.22. Deny Access Need Group
Description | |||
---|---|---|---|
This operation is used when a given Access Need Group with
optional necessity has been denied.
Inputs
| | ||
GRANT
| An Access Grant | ||
GROUP
| An Access Need Group |
-
For each Access Need
NEED
inGROUP
-
Call § 8.4.23 Deny Data Grant with inputs:
NEED hasDataGrant
,GRANT
-
Call § 8.4.36 Deny Remote Data Grant with inputs:
NEED hasRemoteDataGrant
,GRANT
-
-
For each Trusted Need
TNEED
inGROUP
-
Call § 8.4.40 Deny Trusted Grant with inputs:
NEED hasTrustedGrant
,GRANT
-
8.4.23. Deny Data Grant
Description | |||
---|---|---|---|
This operation is used when a given Data Grant has been denied.
Inputs
| | ||
DG
| A Data Grant | ||
GRANT
| The Access Grant that DG is linked to
|
-
Let
DG scopeOfGrant
beinterop:NoAccess
-
For each Referenced Data Grant
REFDG
linked viaDG hasReferencedDataGrant
-
Call § 8.4.24 Deny Referenced Data Grant with inputs:
REFDG
,DG
-
8.4.24. Deny Referenced Data Grant
Description | |||
---|---|---|---|
This operation is used when a given Referenced Data Grant has been denied.
Inputs
| | ||
REFDG
| A Referenced Data Grant | ||
DG
| The Data Grant that REFDG is linked to
|
-
Let
REFDG scopeOfGrant
beinterop:NoAccess
8.4.25. Select All Data Instances
Description | |||
---|---|---|---|
Used to select all Data Instances for a given Data Grant.
Inputs
| | ||
DG
| The Data Grant | ||
GRANT
| The Access Grant that DATAGRANT is associated with
|
-
Let
DG scopeOfGrant
beinterop:AllInstances
-
Remove all links for
DG hasDataInstance
-
For each Referenced Data Grant
REFDG
linked viaDG hasReferencedDataGrant
-
Call § 8.4.26 Select All Referenced Data Instances with inputs:
REFDG
-
8.4.26. Select All Referenced Data Instances
Description | |||
---|---|---|---|
Used to select all Data Instances for a given Referenced Data Grant.
Inputs
| | ||
REFDG
| The Referenced Data Grant |
-
Let
REFDG scopeOfGrant
beinterop:AllInstances
-
Remove all links for
REFDG hasDataInstance
8.4.27. Select Specific Data Instance
Description | |||
---|---|---|---|
Used to select specific Data Instances for a given Data Grant. If the Data Grant has any Referenced Data Grants,
this will set their scope to interop:InheritInstances .
Inputs
| | ||
DI
| A Data Instance selected for access | ||
DG
| The Data Grant that DI is associated with
| ||
GRANT
| The Access Grant that DG is associated with
|
-
Let
DG scopeOfGrant
beinterop:SelectedInstances
-
Let
DG hasDataInstance
be linked to one unique instance ofDI
-
For each Referenced Data Grant
REFDG
linked viaDG hasReferencedDataGrant
-
Call § 8.4.28 Select Inherited Referenced Data Instance with inputs:
REFDG
,DG
-
8.4.28. Select Inherited Referenced Data Instance
Description | |||
---|---|---|---|
Used to set the scope of a Referenced Data Grant to inherited access.
Inputs
| | ||
REFDG
| The Referenced Data Grant to adjust | ||
DG
| The Data Grant that REFDG is linked to
|
-
Let
REFDG scopeOfGrant
beinterop:InheritInstances
-
Remove all links via
REFDG hasDataInstance
8.4.29. Select Specific Referenced Data Instance
Description | |||
---|---|---|---|
Used to set the scope of a Referenced Data Grant to inherited access.
Inputs
| | ||
DI
| A Data Instance selected for access | ||
REFDG
| The Referenced Data Grant to adjust | ||
DG
| The Data Grant that REFDG is linked to
|
-
Let
REFDG scopeOfGrant
beinterop:SelectedInstances
-
Let
REFDG hasDataInstance
be linked to one unique instance ofDI
8.4.30. Select All Remote Instances
Description | |||
---|---|---|---|
Used to select all received Data Grants and Referenced Data Grants across all Remote Agent Data Registrations for a given Remote Data Grant.
Inputs
| | ||
RDG
| The Remote Data Grant | ||
GRANT
| The Access Grant that RDG is associated with
|
-
Let
RDG scopeOfGrant
beinterop:AllRemote
-
Remove all links for
RDG hasRemoteDataFromAgent
-
Remove all links for
RDG hasDataGrant
-
Remove all links for
RDG hasReferencedDataGrant
-
For each Referenced Remote Data Grant
REFRDG
linked viaRDG hasReferencedRemoteDataGrant
-
Call § 8.4.31 Select All Referenced Remote Instances with inputs:
REFRDG
,RDG
-
8.4.31. Select All Referenced Remote Instances
Description | |||
---|---|---|---|
Used to select all received Data Grants and Referenced Data Grants across all Remote Agent Data Registrations for a given Referenced Remote Data Grant.
Inputs
| | ||
REFRDG
| The Referenced Remote Data Grant | ||
RDG
| The Remote Data Grant that REFRDG is associated with
|
-
Let
REFRDG scopeOfGrant
beinterop:AllRemote
-
Remove all links for
REFDG hasRemoteDataFromAgent
-
Remove all links for
REFDG hasDataGrant
-
Remove all links for
REFDG hasReferencedDataGrant
8.4.32. Select All Remote From Agent
Description | |||
---|---|---|---|
Used to select all received Data Grants and Referenced Data Grants associated with a given Remote Agent Data Registration as part of
a specific Remote Data Grant.
Inputs
| | ||
RADR
| The selected Remote Agent Data Registration | ||
RDG
| The Remote Data Grant | ||
GRANT
| The Access Grant that RDG is associated with
|
-
Let
RDG scopeOfGrant
beinterop:AllRemoteFromAgent
-
Remove all links for
RDG hasDataGrant
-
Remove all links for
RDG hasReferencedDataGrant
-
Let
RDG hasRemoteDataFromAgent
be linked to one unique instance ofRADR
-
For each Referenced Remote Data Grant
REFRDG
linked viaRDG hasReferencedRemoteDataGrant
-
Call § 8.4.33 Select All Referenced Remote From Agent with inputs:
RADR
,REFRDG
-
8.4.33. Select All Referenced Remote From Agent
Description | |||
---|---|---|---|
Used to select all received Data Grants and Referenced Data Grants associated with a given Remote Agent Data Registration as part of
a specific Referenced Remote Data Grant.
Inputs
| | ||
RADR
| The selected Remote Agent Data Registration | ||
REFRDG
| The Referenced Remote Data Grant | ||
RDG
| The Remote Data Grant that REFRDG is associated with
|
-
Let
REFRDG scopeOfGrant
beinterop:AllRemoteFromAgent
-
Remove all links for
REFRDG hasDataGrant
-
Remove all links for
REFRDG hasReferencedDataGrant
-
Let
REFRDG hasRemoteDataFromAgent
be linked to one unique instance ofRADR
8.4.34. Select Specific Remote Agent Data Grants
Description | |||
---|---|---|---|
Used to select specific Data Grants and Referenced Data Grants associated with a given Remote Agent Data Registration as part of
a specific Remote Data Grant.
Inputs
| | ||
DATAGRANT
| A Data Grant or Referenced Data Grant selected for access | ||
RDG
| The Remote Data Grant that DATAGRANT is associated with
| ||
GRANT
| The Access Grant that RDG is associated with
|
-
Let
RDG scopeOfGrant
beinterop:SelectedRemote
-
Remove all links for
RDG hasRemoteDataFromAgent
-
If
DATAGRANT
is a Data Grant -
Let
RDG hasDataGrant
be linked toDATAGRANT
-
If
DATAGRANT
is a Referenced Data Grant -
Let
RDG hasReferencedDataGrant
be linked toDATAGRANT
8.4.35. Select Specific Referenced Remote Agent Data Instances
Description | |||
---|---|---|---|
Used to select specific Data Grants and Referenced Data Grants associated with a given Remote Agent Data Registration as part of a
specific Referenced Remote Data Grant.
Inputs
| | ||
DATAGRANT
| A Data Grant or Referenced Data Grant selected for access | ||
REFRDG
| The Referenced Remote Data Grant that DATAGRANT is associated with
| ||
RDG
| The Remote Data Grant that REFRDG is associated with
|
-
Let
REFRDG scopeOfGrant
beinterop:SelectedRemote
-
Remove all links for
REFRDG hasRemoteDataFromAgent
-
If
DATAGRANT
is a Data Grant -
Let
REFRDG hasDataGrant
be linked toDATAGRANT
-
If
DATAGRANT
is a Referenced Data Grant -
Let
REFRDG hasReferencedDataGrant
be linked toDATAGRANT
8.4.36. Deny Remote Data Grant
Description | |||
---|---|---|---|
This operation is used when a given Remote Data Grant with
optional necessity has been denied.
Inputs
| | ||
RDG
| A Remote Data Grant | ||
GRANT
| An Access Grant |
-
Let
RDG scopeOfGrant
beinterop:NoAccess
-
For each Referenced Remote Data Grant
REFRDG
linked viaRDG hasReferencedRemoteDataGrant
-
Call § 8.4.37 Deny Referenced Remote Data Grant with inputs:
REFRDG
,GRANT
-
8.4.37. Deny Referenced Remote Data Grant
Description | |||
---|---|---|---|
This operation is used when a given Referenced Remote Data Grant with
optional necessity has been denied.
Inputs
| | ||
REFRDG
| A Referenced Access Need | ||
GRANT
| An Access Grant |
-
Let
REFRDG scopeOfGrant
beinterop:NoAccess
8.4.38. Select Trusted Registry Set
Description | |||
---|---|---|---|
Used to select an entire Registry Set of a given
registry type for a Trusted Grant.
Inputs
| | ||
SET
| The Registry Set selected for access | ||
TG
| The Trusted Grant that SET is associated with
| ||
GRANT
| The Access Grant that TG is associated with
|
-
Let
TG scopeOfGrant
beinterop:TrustedAccess
-
Let
TG trustedWith
beSET
-
Let
TG trustedWithType
beSET rdf:type
8.4.39. Select Specific Trusted Registry
Description | |||
---|---|---|---|
Used to select a specific Registry of a given registry
type for a Trusted Grant.
Inputs
| | ||
REG
| The Registry selected for access | ||
TG
| The Trusted Grant that REG is associated with
| ||
GRANT
| The Access Grant that TG is associated with
|
-
Let
TG scopeOfGrant
beinterop:TrustedAccess
-
Let
TG trustedWith
beREG
-
Let
TG trustedWithType
beSET rdf:type
8.4.40. Deny Trusted Grant
Description | |||
---|---|---|---|
This operation is used when a given Trusted Grant has been denied.
Inputs
| | ||
TG
| A Trusted Grant | ||
GRANT
| An Access Grant |
-
Let
TG scopeOfGrant
beinterop:NoAccess
9. Access Receipts
9.1. Overview
When an Agent grants access to another Agent or Application, an Access Receipt is provided to the grantee that communicates what they have been given access to, and why.
Access Receipts are sent to an Agent’s Access Inbox. When the grantee is an Application, the Agent will store the Access Receipt in an Application Registration in their Application Registry.
Access Receipts received by an Agent are used to populate and maintain their Remote Data Registry. This allows the Agent and their Applications to lookup and access data that been shared with them.
When an Agent receives an Access Receipt, it is stored in their Access Receipt Registry.
9.2. Data Model
9.2.1. Access Receipt Registry Set
An Access Receipt Registry Set is a Registry Set specifically made up of Access Receipt Registries.
AccessReceiptRegistrySet a rdfs:subClassOf RegistrySet | ||
---|---|---|
Property | Range | Description |
hasRegistry | Registry | Link to associated Access Receipt Registries |
The AccessReceiptRegistrySetShape is used to validate an instance of the AccessReceiptRegistrySet class.
<#AccessReceiptRegistrySetShape> { a [ interop: AccessReceiptRegistrySet ] ; interop: hasRegistry IRI+}
The AccessReceiptRegistrySetTree is assigned to a resource to ensure it will validate against the AccessReceiptRegistrySetShape.
<#AccessReceiptRegistrySetTree> a st: ShapeTree ; st: expectsType st: ShapeTreeResource ; st: validatedBy <interops#AccessReceiptRegistrySetShape> .
9.2.2. Access Receipt Registry
An Access Receipt Registry is a collection of Access Receipts stored in a specific location in a pod.
AccessReceiptRegistry a rdfs:subClassOf Registry | ||
---|---|---|
Property | Range | Description |
hasRegistration | Registration | Link to associated Access Receipts |
The AccessReceiptRegistryShape is used to validate an instance of the AccessReceiptRegistry class.
<#AccessReceiptRegistryShape> { a [ interop: AccessReceiptRegistry ] ; interop: hasRegistration IRI*}
The AccessReceiptRegistryTree is assigned to a container resource to ensure that it will validate against the AccessReceiptRegistryShape, and contain only conformant instances of the AccessReceiptTree.
<#AccessReceiptRegistryTree> a st: ShapeTree ; st: expectsType st: ShapeTreeContainer ; st: validatedBy <interops#AccessReceiptRegistryShape> ; st: contains <#AccessReceiptTree> , st: AllowNone .
9.2.3. Access Receipt
An Agent provides an Access Receipt to another Agent or Application after granting them access to some scope of data as the Access Grant Subject of an Access Grant.
Access Receipts extend the Access Grant class with additional properties that provide context to the recipient. Otherwise, they retain the same structure, linked to any Access Need Groups used to formulate the Access Grant, as well as any Data Grants, Remote Data Grants, or Trusted Grants that detail the scope of access granted.
AccessReceipt a rdfs:subClassOf AccessGrant | ||
---|---|---|
Property | Range | Description |
registeredBy | Agent | Agent that registered the Access Receipt |
registeredWith | Application | Application used to create the Access Receipt |
registeredAt | xsd:dateTime | Date and time the Access Receipt was created |
updatedAt | xsd:dateTime | Date and time the Access Receipt was updated |
providedAt | xsd:dateTime | Date and time the Access Receipt was provided |
fromAgent | Agent | Agent whose data is being shared through the Access Receipt |
viaAgent | Agent | Agent who granted access and delivered the Access Receipt.
This can be different than fromAgent when access is being managed
by a Trusted Agent of fromAgent .
|
hasAccessGrantSubject | AccessGrantSubject | Links to the Access Grant Subject that was granted access. |
hasAccessNeedGroup | AccessNeedGroup | Links to an Access Need Group associated with the Access Receipt. |
hasDataGrant | DataGrant | Links to a Data Grant associated with the Access Receipt. |
hasTrustedGrant | TrustedGrant | Links to a Trusted Grant associated with the Access Receipt. |
hasRemoteDataGrant | RemoteDataGrant | Links to a Remote Data Grant associated with the Access Receipt. |
The AccessReceiptShape is used to validate an instance of the AccessReceipt class.
<#AccessReceiptShape> { a [ interop: AccessReceipt ] ; interop: registeredBy IRI; interop: registeredWith IRI?; interop: registeredAt xsd: dateTime ; interop: updatedAt xsd: dateTime ; interop: providedAt xsd: dateTime ; interop: fromAgent IRI; # Agent who sent the receipt interop: viaAgent IRI; # Trusted agent on behalf of fromAgent interop: hasAccessGrantSubject @<#:AccessGrantSubject> ; # Subject / recipient interop: hasAccessNeedGroup @<#:AccessNeedGroupShape> +; ( interop: hasDataGrant @<#:DataGrantShape> + |interop: hasTrustedGrant @<#:TrustedGrantShape> + |interop: hasRemoteDataGrant @<#:RemoteDataGrantShape> +) ; }
The AccessReceiptTree is assigned to a resource via the AccessGrantRegistryTree, and ensures that the assigned resource will validate against the AccessReceiptShape.
<#AccessReceiptTree> a st: ShapeTree ; st: expectsType st: ShapeTreeResource ; st: validatedBy <interops#AccessReceiptShape> .
9.3. Resource Hierarchy
Resource | Class | Shape | Shape Tree |
---|---|---|---|
/profile/
| - | - | ProfileTree |
-- receipt#set
| AccessReceiptRegistrySet | AccessReceiptRegistrySetShape | AccessReceiptRegistrySetTree |
/receipts/#registry
| AccessReceiptRegistry | AccessReceiptRegistryShape | AccessReceiptRegistryTree |
-- fa6d6553...5a#receipt
| AccessReceipt | AccessReceiptShape | AccessReceiptTree |
-- d49eae8c...6b#receipt
| AccessReceipt | AccessReceiptShape | AccessReceiptTree |
-- 506a0cee...02#receipt
| AccessReceipt | AccessReceiptShape | AccessReceiptTree |
The Access Receipt Registry Set and the Access Receipt Registry MAY or MAY NOT be on the same pod.
Access Receipt Registry Set and Access Receipt Registry resources MAY use any resource or subject names.
Access Receipts MUST use UUIDs for resource names.
9.4. Operations
9.4.1. Provide Access Receipt
Description | |||
---|---|---|---|
This operation takes an input Access Grant and provides an Access Receipt to the grantee. In the event that the grantee is an Application it may provide the Access Receipt in the Application Registration for the Application. Inputs
| | ||
GRANT
| Access Grant to provide a receipt for
Outputs
| | |
Access Receipt | that was provided for GRANT
|
-
Let
SUBJECT
be the Access Grant Subject linked viaGRANT hasAccessGrantSubject
-
Let
AGENT
beSUBJECT accessByAgent
-
Let
APP
beSUBJECT accessByApplication
-
If
APP
is not empty-
If
APP receivesAccessReceipt
isinterop:ReceiptInRegistration
-
Let
RECEIPT
be result of § 9.4.2 Provide Receipt in Application Registration with inputs:GRANT
-
-
If
APP receivesAccessReceipt
isinterop:ReceiptInMessage
-
Let
RECEIPT
be result of § 9.4.3 Provide Receipt in Message with inputs:GRANT
-
-
-
If
APP
is empty andAGENT
is not empty-
Return error if
AGENT receivesAccessReceipt
is notinterop:ReceiptInMessage
-
Let
RECEIPT
be result of § 9.4.3 Provide Receipt in Message with inputs:GRANT
-
-
Return
RECEIPT
9.4.2. Provide Receipt in Application Registration
Description | |||
---|---|---|---|
This operation provides an Access Receipt for an Access Grant in the Application Registration of the Application in the Access Grant Subject. Inputs
| | ||
GRANT
| Access Grant to provide a receipt for
Outputs
| | |
Access Receipt | for GRANT stored in an Application Registration
|
-
Let
RECEIPT
be an empty Access Receipt -
Let
SUBJECT
be the Access Grant Subject linked viaGRANT hasAccessGrantSubject
-
Let
GRANTOR
be the current Agent -
Let
OWNER
be the Agent owner of the storage access is being granted from -
Let
APP
beSUBJECT accessByApplication
-
Let
RECEIPT fromAgent
beOWNER
-
Let
RECEIPT viaAgent
beGRANTOR
-
Let
RECEIPT providedAt
be the current time -
Let
RECEIPT hasAccessGrantSubject
beSUBJECT
-
Let
RECEIPT hasAccessNeedGroup
be all Access Need Groups linked viaGRANT hasAccessNeedGroup
-
Let
RECEIPT hasDataGrant
be all Data Grants linked viaGRANT hasDataGrant
-
Let
RECEIPT hasTrustedGrant
be all Trusted Grants linked viaGRANT hasTrustedGrant
-
Let
RECEIPT hasRemoteDataGrant
be all Remote Data Grants linked viaGRANT hasRemoteDataGrant
-
Let
APPREG
be result of § 4.5.1 Load Application Registration with inputs:OWNER
,APP
-
Call § 4.5.2 Register Application if
APPREG
is empty
-
-
Post
RECEIPT
toAPPREG
container -
Let
CURRENT
beAPPREG hasAccessReceipt
-
Remove
CURRENT
if it exists -
Let
APPREG hasAccessReceipt
beCURRENT
-
Return
RECEIPT
9.4.3. Provide Receipt in Message
Description | |||
---|---|---|---|
This operation provides an Access Receipt for an Access Grant to a given Agent by delivering it to their access inbox. Inputs
| | ||
GRANT
| Access Grant to provide a receipt for
Outputs
| | |
Access Receipt | for GRANT posted to the grantee Agent’s access inbox
|
-
Let
RECEIPT
be an empty Access Receipt -
Let
SUBJECT
be the Access Grant Subject linked viaGRANT hasAccessGrantSubject
-
Let
GRANTEE
beSUBJECT accessByAgent
-
Let
GRANTOR
be the current Agent -
Let
OWNER
be the Agent owner of the storage access is being granted from -
Let
RECEIPT fromAgent
beOWNER
-
Let
RECEIPT viaAgent
beGRANTOR
-
Let
RECEIPT providedAt
be the current time -
Let
RECEIPT hasAccessGrantSubject
beSUBJECT
-
Let
RECEIPT hasAccessNeedGroup
be all Access Need Groups linked viaGRANT hasAccessNeedGroup
-
Let
RECEIPT hasDataGrant
be all Data Grants linked viaGRANT hasDataGrant
-
Let
RECEIPT hasTrustedGrant
be all Trusted Grants linked viaGRANT hasTrustedGrant
-
Let
RECEIPT hasRemoteDataGrant
be all Remote Data Grants linked viaGRANT hasRemoteDataGrant
-
Post
RECEIPT
toGRANTEE hasAccessInbox
-
Return
RECEIPT
9.4.4. Record Access Receipt
Description | |||
---|---|---|---|
This operation stores a new Access Receipt in an Access Grant Registry, which in turn will update Remote Data Registries to reflect the access granted in the Access Receipt. Inputs
| | ||
RECEIPT
| Access Receipt to record | ||
REGISTRY
| Access Receipt Registry to store receipts in
Outputs
| | |
Access Receipt | Stored in REGISTRY with corresponding entries in the Remote Data Registry
|
-
Let
CURRENT
be an Access Receipt returned by § 9.4.5 Load Access Receipt with inputs:RECEIPT fromAgent
,REGISTRY
-
If
CURRENT
is empty-
Add
RECEIPT
toREGISTRY
-
Link
RECEIPT
toREGISTRY
viaREGISTRY hasRegistration
-
-
If
CURRENT
is not empty-
Update
CURRENT
withRECEIPT
-
-
Call § 10.4.3 Update Remote Data with inputs:
RECEIPT
-
Return
RECEIPT
9.4.5. Load Access Receipt
Description | |||
---|---|---|---|
This operation looks up an Access Receipt in
an Access Receipt Registry Inputs
| | ||
AGENT
| Agent owner of the shared data | ||
REGISTRY
| Access Receipt Registry to lookup
Outputs
| | |
Access Receipt | Corresponding to AGENT in REGISTRY
|
-
For each Access Receipt
RECEIPT
included inREGISTRY hasRegistration
-
return
RECEIPT
ifRECEIPT fromAgent
==AGENT
-
10. Remote Data Registration
10.1. Overview
Remote Data Registration lets Agents keep track of data that other Agents have shared with them.
When an Agent shares data with another Agent, they record that decision with an Access Grant, and send an Access Receipt to the grantee. The Access Receipt is used to update the grantee’s Remote Data Registry with pointers to that remote data that was shared with them.
10.2. Data Model
10.2.1. Remote Data Registry Set
A Remote Data Registry Set is a Registry Set specifically made up of Remote Data Registries.
RemoteDataRegistrySet a rdfs:subClassOf RegistrySet | ||
---|---|---|
Property | Range | Description |
hasRegistry | Registry | Link to associated Remote Data Registries |
The RemoteDataRegistrySetShape is used to validate an instance of the RemoteDataRegistrySet class.
<#RemoteDataRegistrySetShape> { a [ interop: RemoteDataRegistrySet ] ; interop: hasRegistry IRI+}
The RemoteDataRegistrySetTree is assigned to a resource to ensure it will validate against the RemoteDataRegistrySetShape.
<#RemoteDataRegistrySetTree> a st: ShapeTree ; st: expectsType st: ShapeTreeResource ; st: validatedBy <interops#RemoteDataRegistrySetShape> .
10.2.2. Remote Data Registry
A Remote Data Registry is a collection of Remote Data Registrations stored in a specific location in a pod.
RemoteDataRegistry a rdfs:subClassOf Registry | ||
---|---|---|
Property | Range | Description |
hasRemoteDataRegistration | RemoteDataRegistration | Link to associated Remote Data Registrations |
The RemoteDataRegistryShape is used to validate an instance of the RemoteDataRegistry class.
<#RemoteDataRegistryShape> { a [ interop: RemoteDataRegistry ] ; interop: hasRemoteDataRegistration IRI*}
The RemoteDataRegistryTree is assigned to a container resource to ensure that it will validate against the RemoteDataRegistryShape, and contain only conformant instances of the RemoteDataRegistrationTree.
<#RemoteDataRegistryTree> a st: ShapeTree ; st: expectsType st: ShapeTreeContainer ; st: validatedBy <interops#RemoteDataRegistryShape> ; st: contains <#RemoteDataRegistrationTree> , st: AllowNone .
10.2.3. Remote Data Registration
A Remote Data Registration represents data shared by other Agents corresponding to a given shape tree, each of which is associated with a Remote Agent Data Registration.
Each Remote Agent Data Registration creates a useful authorization boundary for remote data from a given Agent.
RemoteDataRegistration a rdfs:subClassOf Registration | ||
---|---|---|
Property | Range | Description |
registeredBy | Agent | Agent that registered the Remote Data Registration |
registeredWith | Application | Application used to create the Remote Data Registration |
registeredAt | xsd:dateTime | Date and time the Remote Data Registration was created |
updatedAt | xsd:dateTime | Date and time the Remote Data Registration was updated |
registeredShapeTree | st:ShapeTree | Associated shape tree that all linked Remote Agent Data Registrations must conform to |
hasRemoteAgentDataRegistration | RemoteAgentDataRegistration | Link to associated Remote Agent Data Registrations |
The RemoteDataRegistrationShape is used to validate an instance of the RemoteDataRegistration class.
<#RemoteDataRegistrationShape> { a [ interop: RemoteDataRegistration ] ; interop: registeredBy IRI; interop: registeredWith IRI; interop: registeredAt xsd: dateTime ; interop: updatedAt xsd: dateTime ; interop: registeredShapeTree IRIinterop: hasRemoteAgentDataRegistration IRI*; }
The RemoteDataRegistrationTree is assigned to a container resource to ensure that it will validate against the RemoteDataRegistrationShape, and contain only conformant instances of the RemoteAgentDataRegistrationTree.
<#RemoteDataRegistrationTree> a st: ShapeTree ; st: expectsType st: ShapeTreeContainer ; st: validatedBy <interops#RemoteDataRegistrationShape> ; st: contains <#RemoteAgentDataRegistrationTree> , st: AllowNone .
10.2.4. Remote Agent Data Registration
An Agent maintains a Remote Agent Data Registration to represent access to a Data Registration that another Agent has shared with them. It may represent access to the entire Data Registration, or only to a select group of Data Instances within.
A Remote Agent Data Registration is created when an Agent receives an Access Receipt from another Agent that includes access to a given Data Registration.
-
A Remote Agent Data Registration MUST be associated with at least one Data Grant or Referenced Data Grant sourced from the Access Receipt linked via
hasAccessReceipt
-
Each associated Data Grant or Referenced Data Grant MUST be stored as an individual resource in the Remote Agent Data Registration container.
-
If an Access Receipt with a corresponding Data Grant or Referenced Data Grant is received that changes the access to a shared Data Registration, the corresponding Remote Agent Data Registrations, stored Data Grants, and/or stored Referenced Data Grants MUST be updated, and removed altogether if that access is removed.
RemoteAgentDataRegistration a rdfs:subClassOf Registration | ||
---|---|---|
Property | Range | Description |
registeredBy | Agent | Agent that registered the Remote Agent Data Registration |
registeredWith | Application | Application used to create the Remote Agent Data Registration |
registeredAt | xsd:dateTime | Date and time the Remote Agent Data Registration was created |
updatedAt | xsd:dateTime | Date and time the Remote Agent Data Registration was updated |
registeredShapeTree | st:ShapeTree | Shape tree associated with the shared Data Registration |
hasDataRegistration | DataRegistration | Link to the Data Registration that was shared |
fromAgent | Agent | Link to the Agent who the shared Data Registration belongs to |
hasAccessReceipt | AccessReceipt | Link to Access Receipt representing data share |
satisfiesDataGrant | DataGrant, ReferencedDataGrant | Link to Data Grants or Referenced Data Grants that
detail the scope of access shared from fromAgent for
the shared Data Registration. These are contained in the
linked Access Receipt, but each is added as a resource
into the Remote Agent Data Registration container, for
authorization boundary purposes.
|
The RemoteAgentDataRegistrationShape is used to validate an instance of the RemoteAgentDataRegistration class.
<#RemoteAgentDataRegistration> { a [ interop: RemoteAgentDataRegistration ] ; interop: registeredBy IRI; interop: registeredWith IRI; interop: registeredAt xsd: dateTime ; interop: updatedAt xsd: dateTime ; interop: hasDataRegistration IRI; interop: fromAgent IRI; interop: registeredShapeTree IRI; interop: hasAccessReceipt IRI*; interop: satisfiesDataGrant IRI+}
The RemoteAgentDataRegistrationTree is assigned to a resource via the RemoteDataRegistrationTree, and ensures that the assigned resource will validate against the RemoteAgentDataRegistrationShape.
<#RemoteAgentDataRegistrationTree> a st: ShapeTree ; st: expectsType st: ShapeTreeContainer ; st: validatedBy <interops#RemoteAgentDataRegistrationShape> ; st: contains <#DataGrantTree> , <#ReferencedDataGrantTree> , st: AllowNone .
10.3. Resource Hierarchy
The Remote Data Registry Set and the Remote Data Registry MAY or MAY NOT be on the same pod.
Remote Data Registry Set and Remote Data Registry resources MAY use any resource or subject names.
Remote Data Registrations, Remote Agent Data Registrations, Data Grants, and Referenced Data Grants MUST use UUIDs for resource names.
Remote Agent Data Registrations are organized under Remote Data Registrations by interop:registeredShapeTree
to
provide rational boundaries for authorization.
Data Grants and Referenced Data Grants are extracted from the
associated Access Receipt are stored individually under
the relevant Remote Agent Data Registration, and linked to it via interop:satisfiesDataGrant
. This allows the Agent to limit
remote data access by grant for a given Remote Agent Data Registration.
10.4. Operations
-
§ 10.4.1 Load Remote Data Registration - Lookup a Remote Data Registration by shape tree
-
§ 10.4.2 Create Remote Data Registration - Create a new Remote Data Registration
-
§ 10.4.3 Update Remote Data - Updates a Remote Data Registry based on the contents of an Access Receipt
-
§ 10.4.4 Load Remote Agent Data Registration - Lookup a Remote Agent Data Registration by URI of the shared Data Registration
-
§ 10.4.5 Create Remote Agent Data Registration - Create a new Remote Agent Data Registration
-
§ 10.4.6 Update Remote Agent Data Registration - Update a specific Remote Agent Data Registration
10.4.1. Load Remote Data Registration
Description | |||
---|---|---|---|
Lookup a Remote Data Registration for a given shape tree TREE in a Remote Data Registry REGISTRY
Inputs
| | ||
TREE
| The shape tree for the Remote Data Registration | ||
REGISTRY
| The Remote Data Registry to search for a Remote Data Registration
Outputs
| | |
Remote Data Registration | Corresponding to TREE in REGISTRY
|
-
For each Remote Data Registration
RDR
inREGISTRY
linked viaREGISTRY hasRemoteDataRegistration
-
return
RDR
ifRDR registeredShapeTree
==TREE
-
10.4.2. Create Remote Data Registration
Description | |||
---|---|---|---|
Create a Remote Data Registration for a given shape tree TREE in a Remote Data Registry REGISTRY
Inputs
| | ||
TREE
| The shape tree for the Remote Data Registration | ||
REGISTRY
| The Remote Data Registry for the Remote Data Registration
Outputs
| | |
Remote Data Registration | Corresponding to TREE in REGISTRY
|
-
Let
EXISTING
be a Remote Data Registration returned by § 10.4.1 Load Remote Data Registration with inputs:TREE
,REGISTRY
-
Error if
EXISTING
-
-
Let
RDR
be an empty Remote Data Registration -
Let
RDR registeredBy
be the current Agent -
Let
RDR registeredWith
be the current Application -
Let
RDR registeredAt
be the current timestamp -
Let
RDR updatedAt
be the current timestamp -
Let
RDR registeredShapeTree
beTREE
-
PUT
RDR
intoREGISTRY
container -
Link
RDR
toREGISTRY
viaREGISTRY hasRemoteDataRegistration
-
Return
RDR
10.4.3. Update Remote Data
Description | |||
---|---|---|---|
This operation updates a Remote Data Registry It iterates over each Data Grant linked via All Data Grants and Referenced Data Grants are added to
a hash map The end result is the keys of Each Data Registration and the array of grants that affect it are then passed to § 10.4.6 Update Remote Agent Data Registration. Inputs
| | ||
RECEIPT
| An Access Receipt representing data shared with an Agent | ||
REGISTRY
| A Remote Data Registry for the Agent
Outputs
| | |
Access Receipt | Updated with remote data associations |
-
Let
DRHASH
be an empty hash map where a Data Registration is key and the value is an array of Data Grants and/or Referenced Data Grants. -
For each Data Grant
DG
linked viaRECEIPT hasDataGrant
-
Let
DRKEY
beDG hasDataRegistration
added or found inDRHASH
-
Add
DG
to the value array forDRKEY
if missing -
For each Referenced Data Grant
REFDG
linked viaDG hasReferencedDataGrant
-
Let
REFDRKEY
beREFDG hasDataRegistration
added or found inDRHASH
-
Add
REFDG
to the array forREFDRKEY
if missing
-
-
-
For each Data Registration
DR
inDRHASH
-
Call § 10.4.6 Update Remote Agent Data Registration with inputs:
DR
,DRHASH[DR]
,RECEIPT
-
-
Return
RECEIPT
10.4.4. Load Remote Agent Data Registration
Description | |||
---|---|---|---|
Lookup a Remote Agent Data Registration RADREG in a given Remote Data Registry based on the URI of a
shared Data Registration.
Inputs
| | ||
DATAREG
| A shared Data Registration to lookup | ||
REGISTRY
| A Remote Data Registry to search
Outputs
| | |
Remote Agent Data Registration | Corresponding to DATAREG in REGISTRY
|
-
For each Remote Data Registration
RDR
inREGISTRY
linked viaREGISTRY hasRemoteDataRegistration
-
If
RDR registeredShapeTree
==DATAREG registeredShapeTree
-
For each Remote Agent Data Registration
RADR
linked viaRDR hasRemoteAgentDataRegistration
-
return
RADR
ifRADR hasDataRegistration
==DATAREG
-
-
10.4.5. Create Remote Agent Data Registration
Description | |||
---|---|---|---|
Creates a Remote Agent Data Registration in a Remote Data Registry based on a shared Data Registration in an Access Receipt.
Inputs
| | ||
DR
| The shared Data Registration | ||
RECEIPT
| The Access Receipt that DR is shared through
| ||
REGISTRY
| A Remote Data Registry for the Agent
Outputs
| | |
Remote Agent Data Registration | Created upon success |
-
Let
RDR
be a Remote Data Registration returned by § 10.4.1 Load Remote Data Registration with inputs:DR registeredShapeTree
,REGISTRY
-
If
RDR
is missing, letRDR
be a Remote Data Registration returned by § 10.4.2 Create Remote Data Registration with inputs:DR registeredShapeTree
,REGISTRY
-
-
Let
RADR
be an empty Remote Agent Data Registration -
Let
RADR registeredBy
be the current Agent -
Let
RADR registeredWith
be the current Application -
Let
RADR registeredAt
be the current timestamp -
Let
RADR updatedAt
be the current timestamp -
Let
RADR hasDataRegistration
beDR
-
Let
RADR registeredShapeTree
beDR registeredShapeTree
-
Let
RADR fromAgent
beRECEIPT fromAgent
-
Let
RADR hasAccessReceipt
beRECEIPT
-
PUT
RADR
into theRDR
container -
Link
RADR
toRDR
viaRDR hasRemoteAgentDataRegistration
-
Return
RADR
10.4.6. Update Remote Agent Data Registration
Description | |||
---|---|---|---|
Update an existing Remote Agent Data Registration with a set of Data Grants and/or Referenced Data Grants.
Create the Remote Agent Data Registration if it doesn’t exist.
Inputs
| | ||
DR
| The shared Data Registration | ||
DATAGRANTS
| An array of Data Grants and Referenced Data Grants associated with DR in RECEIPT
| ||
RECEIPT
| Access Receipt associated with DR and DATAGRANTS
Outputs
| | |
Remote Agent Data Registration | Updated based on the input DATAGRANTS
|
-
Let
RADR
be a Remote Agent Data Registration returned from calling § 10.4.4 Load Remote Agent Data Registration with inputs:DR
,REGISTRY
-
If
RADR
is missing-
Call § 10.4.5 Create Remote Agent Data Registration with inputs:
RECEIPT
,REGISTRY
-
-
For each
DATAGRANT
inDATAGRANTS
-
PUT
DATAGRANT
intoRADR
container if it does not already exist -
PATCH
DATAGRANT
inRADR
container if it already exists
-
-
Return
RADR
11. Security
11.1. Application Authorization
For authorization purposes, client Applications in use today fall into two buckets:
Strongly identifiable applications can be identified by third parties independently from the user or Agent controlling them. Only server-side applications are strongly identifiable. As confidential clients, they can keep secrets and can present attestations and third-party credentials via DNS / domain certificates.
In the case of a strongly identifiable application, the identity of Agent and the Application are one and the same. The Application has its own identity. A given Agent can authorize a given Application to access data based solely on the identity of that Application.
Weakly identifiable applications include in-browser Javascript Applications and native desktop or mobile Applications. They are considered weakly identifiable because they are not able to keep secrets on an instance level. They are often referred to as public clients. Native apps should be strongly-identifiable in theory (since they are able to keep secrets on an instance level), but not in practice because the OS manufacturers do not make their trust infrastructure available. Weakly identifiable clients are only strongly identifiable to the user or Agent controlling them.
In the case of Weakly identifiable applications, the ability for a Solid pod to limit access to data by the Application in use is only as strong as the trustworthiness of the Agent piloting that Application, along with their ability to avoid using malicious Applications. The identity of the Application can be manipulated by the Agent in control. This means that Alice can strongly control the Applications that she uses to access her own data, but has limited ability to control the Applications that Bob uses to access the data she shares with him.
12. Definitions
All definitions as stated below should be considered in the context of an interoperable ecosystem for Solid, whether explicitly stated or not.
Solid is a protocol made up of a number of open web standards aimed at decentralizing data on the web.
A Solid pod is a place for storing and accessing data via the Solid protocol, with mechanisms for controlling who or what can access that data.
An interoperable ecosystem is a collection of Solid compatible applications developed by one or more entities, used by a community of users, that can safely access and manipulate the same kinds of data in pods.
A server-side application runs on a dedicated server. They may also act as autonomous authenticated agents.
A user-piloted application runs on a user’s device, with the user as the authenticated agent. They include in-browser javascript applications, native desktop applications, and mobile applications.
An authenticated agent is an agent that has strongly authenticated their identity by proving control of the identity profile document via an authentication protocol such as [WEBID-OIDC].
An identity is a unique URI that can be dereferenced to return an identity profile document. Compatible identity systems include WebID and DID.
An identity profile document is a linked data document obtained by dereferencing the URI for a given identity. It provides information that can be used to prove that a given Agent controls the document.
A WebID is a web resource at an HTTP URI which refers to an agent. An identity profile document can be accessed by dereferencing the WebID. [WEBID]
A DID is a URI that associates a DID subject (e.g. an agent, thing, data model, abstract entity, etc.) with a DID document, equivalent to an identity profile document, to allow trustable interactions with that subject. [DID]
An application identity is a web resource at an HTTP URI that uniquely identifies a given Application, and dereferences to an application profile document.
An application profile document is a linked data document obtained by dereferencing the URI for a given application identity.
An acl resource as defined by [WAC] may be directly associated with a resource or indirectly associated with a resource through inheritance. It determines which authorization subjects can access a resource, and the modes of access they have for it.
An access mode denotes operations (e.g. read, write) that a given authorization subject can perform on a resource.
An authorization subject is the target of a given authorization statement in an acl resource. It is either an Agent (individual, group, server-side application), a User-Piloted Application in use by any Agent, or a combination of a specific Agent using a specific User-Piloted Application.
An authorization statement is ...
A shape provides a schema that RDF data graphs must meet in order to be considered conformant. A shape associated with a given resource in a pod ensures that any data stored in that resource must conform to the associated shape. Shape languages include [SHEX] and [SHACL].
A Shape Tree defines a prospective tree of related resources which can be read and written by applications. The shape tree associates each of these resources with a shape. This allows one to treat a set of related resources as a single grouping, and apply that to a range of operations including access control, data organization, data validation, and data migration. [SHAPETREES]
A Shape Tree Decorator provides additional human-readable description and context for a given shape tree.
A Shape Tree Reference provides the necessary context to associate instances of related shape trees via a ShapePath