Solid Application Interoperability

Editor’s Draft,

This version:
https://solid.github.io/data-interoperability-panel/specification/
Issue Tracking:
Inline In Spec
Editors:
Justin Bingham
Eric Prud'hommeaux
Josh Collins

Abstract

This specification details how Agents and Applications can safely share and interoperate over data in a Solid Pod.

Status of this document

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.

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.

Agent at https://alice.pod.example/profile/id#me
<#me>
  a interop:Agent;
  ######## Registry Sets ########
  interop:hasApplicationRegistrySet <https://alice.pod.example/profile/application#set> ;
  interop:hasDataRegistrySet <https://alice.pod.example/profile/data#set> ;
  interop:hasAccessGrantRegistrySet <https://alice.pod.example/profile/grant#set> ;
  interop:hasAccessReceiptRegistrySet <https://alice.pod.example/profile/receipt#set> ;
  interop:hasRemoteDataRegistrySet <https://alice.pod.example/profile/remote#set> ;
  ######## Inboxes ########
  interop:hasInbox <https://alice.pod.example/inbox/general> ;
  interop:hasAccessInbox <https://alice.pod.example/inbox/access> ;
  ######## Options ########
  interop:receivesAccessReceipt interop:ReceiptInMessage .

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:

Permission model for Agent resources
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.

Application at https://app.example/profile/id#app
<#app>
  a interop:Application ;
  interop:applicationName "Example Application" ;
  interop:applicationDescription "This is a description of the Example Application" ;
  interop:applicationAuthor <https://app.example/org/id#agent> ;
  interop:applicationAuthorName "Example Organization" ;
  interop:applicationThumbnail <https://app.example/profile/thumb.svg> ;
  interop:hasAccessNeedGroup <#exampleAccessNeedGroup> ;
  interop:receivesAccessReceipt interop:ReceiptInRegistration .

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:

Permission model for Application resources
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.

Giving Applications their own private data space in Solid may seem counterintuitive to Solid’s proposition to decouple data and Applications.

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

Data model for application registration

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.

Agent at https://alice.pod.example/profile/id#me linking to an Application Registry Set
<#me>
  a interop:Agent;
  interop:hasApplicationRegistrySet <https://alice.pod.example/profile/application#set> .
An Application Registry Set at https://alice.pod.example/profile/application#set linking to two different Application Registries
<#set>
  a interop:ApplicationRegistrySet;
  interop:hasRegistry <https://alice.pod.example/applications/#registry> ,
                  <https://alice.otherpod.example/applications/#registry> .
An Application Registry at https://alice.pod.example/applications/#registry linking to several Application Registrations
<#registry>
  a interop:ApplicationRegistry ;
  interop:hasRegistration 
    <705563552198b6fb3efc40717872aa2ec35d669c1095cc5d665f499ec5d7e23a/#registration> ,
    <ede6aa50cb9e5fc564fdb4f0dc661685825ee3178355214086be27f9830e2a42/#registration> ,
    <150dca42b3d5661ba10a28e0aff36f212e27b0f7463fe1ef3bf1b5a45b640673/#registration> ,
    <b3564e72a3877c9cfa9e4bc4d9e47e9b7c536ae9927407c8dd00ec3b0069f536/#registration> .
An Application Registration at https://alice.pod.example/applications/705563552198b6fb3efc40717872aa2ec35d669c1095cc5d665f499ec5d7e23a/#registration
<#registration>
  a interop:ApplicationRegistration ;
  interop:registeredBy <https://alice.pod.example/profile/id#me> ;
  interop:registeredWith <https://trusted.example/id#agent> ;
  interop:registeredAt "2020-04-04T20:15:47.000Z"^^xsd:dateTime ;
  interop:updatedAt "2020-04-04T21:11:33.000Z"^^xsd:dateTime ;
  interop:registeredApplication <https://app.example/profile/id#agent> ;
  interop:hasAccessReceipt <./04ca5ba7-0166-4312-ae96-09b9f3a25ba0#receipt> .

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

Resource Class Shape Shape Tree
/profile/ - - ProfileTree
-- application#set ApplicationRegistrySet ApplicationRegistrySetShape ApplicationRegistrySetTree
/applications/#registry ApplicationRegistry ApplicationRegistryShape ApplicationRegistryTree
-- 70556355...c5d7e23a/#registration ApplicationRegistration ApplicationRegistrationShape ApplicationRegistrationTree
---- 04ca5ba7...f3a25ba0#receipt AccessReceipt AccessReceiptShape AccessReceiptTree
---- ex-cache-1122 - - -
-- ede6aa50...830e2a42/#registration ApplicationRegistration ApplicationRegistrationShape ApplicationRegistrationTree
---- 2af133d6...78e343ba#receipt AccessReceipt AccessReceiptShape AccessReceiptTree
---- ex-internal-idx - - -
-- 150dca42...5b640673/#registration ApplicationRegistration ApplicationRegistrationShape ApplicationRegistrationTree
---- 14f8bfb9...e42f7084#receipt AccessReceipt AccessReceiptShape AccessReceiptTree
-- b3564e72...0069f536/#registration ApplicationRegistration ApplicationRegistrationShape ApplicationRegistrationTree

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:

Note: Append+ indicates that Read/Write is granted to the subsequently created resource.

Permission model for Application Registry resources.
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
4.5.1.2. Outputs
4.5.1.3. Operation Details
  1. AGENT provides their identity to APP

  2. APP dereferences the identity of AGENT get AGENT's identity profile document.

  3. Let ARSET be the Application Registry Set linked via AGENT hasApplicationRegistrySet.

    1. Because ARSET is a non-public document, AGENT and APP will be required to furnish a DPoP proof and access token to the Solid Server, obtained via the Solid-OIDC protocol.

  4. For each Application Registry AREGISTRY in ARSET

    1. Let IDSHA256 be the SHA-256 hash of APP's identity

    2. Let STATUS be the HTTP status code returned from a GET or HEAD of https://AREGISTRY/IDSHA256

    3. Return AREGISTRY if STATUS is 200 OK

  5. 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
4.5.2.2. Outputs
4.5.2.3. Operation Details
  1. Let EXISTING be an Application Registration returned from § 4.5.1 Load Application Registration with inputs: AGENT, APP

  2. Return EXISTING if EXISTING is not empty

  3. Let REG be a newly initialized Application Registration

  4. Let REG registeredBy be AGENT

  5. Let REG registeredWith be the identity of the Application executing the operation

  6. Let REG registeredAt be the current date and time

  7. Let REG updatedAt be the current date and time

  8. Let REG registeredApplication be the identity of APP

  9. Let IDSHA256 be the SHA-256 hash of APP's identity

  10. Add REG to the REGISTRY container, using IDSHA256 as the resource name

  11. Assign permissions for REG per the § 4.4 Permission Model

  12. Link REG to REGISTRY via REGISTRY hasRegistration

  13. 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

Data model for data registration

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.

Agent at https://alice.pod.example/profile/id#me linking to a Data Registry Set
<#me>
  a interop:Agent;
  interop:hasDataRegistrySet <https://alice.pod.example/profile/data#set> .
A Data Registry Set at https://alice.pod.example/profile/data#set linking to two different Data Registries
<#set>
  a interop:DataRegistrySet;
  interop:hasRegistry <https://alice.pod.example/data/#registry> ,
                  <https://alice.otherpod.example/data/#registry> .
A Data Registry at https://alice.pod.example/data/#registry linking to several Data Registrations
<#registry>
  a interop:DataRegistry ;
  interop:hasRegistration <8501f084-deb9-4775-8a35-2040df435d21/#registration> ,
                      <df4ab227-2f15-455d-8ca2-fad10fb9f9bc/#registration> ,
                      <d0954df2-e7c3-40b4-9eeb-65df92d9167e/#registration> ,
                      <87da9aa5-3f6c-4bc2-a5d4-adb7efcaee5d/#registration> ,
                      <bc3d8522-7f00-4d90-a01b-54ec01591640/#registration> ,
                      <3a3ee852-ff49-46ea-b7a8-65cec55879a4/#registration> .
A Data Registration at https://alice.pod.example/data/8501f084-deb9-4775-8a35-2040df435d21/#registration
<#registration>
  a interop:DataRegistration ;
  interop:registeredBy <https://alice.pod.example/profile/id#me> ;
  interop:registeredWith <https://app.example/id#agent> ;
  interop:registeredAt "2020-04-04T20:15:47.000Z"^^xsd:dateTime ;
  interop:updatedAt "2020-04-04T21:11:33.000Z"^^xsd:dateTime ;
  interop:registeredShapeTree note:notebookTree ;
  interop:registeredType note:notebook .

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

Resource Class Shape Shape Tree
/profile/ - - ProfileTree
-- data#set DataRegistrySet DataRegistrySetShape DataRegistrySetTree
/data/#registry DataRegistry DataRegistryShape DataRegistryTree
-- 8501f084...2040df43/#registration DataRegistration DataRegistrationShape DataRegistrationTree, FooContainingTree
---- 16e1eae9...ca3805c4/#foo FooInstance FooShape FooTree
---- 886785d2...5ac36b7b/#foo FooInstance FooShape FooTree
---- dae5015c...7ca7a198/#foo FooInstance FooShape FooTree
-- df4ab227...fad10fb9/#registration DataRegistration DataRegistrationShape DataRegistrationTree, BarContainingTree
---- 9b60a354...cb9da85c/#bar BarInstance BarShape BarTree
---- 6e545b74...b15cbdce/#bar BarInstance BarShape BarTree
---- d33e01c8...ac9e3cc6/#bar BarInstance BarShape BarTree
---- 927108fa...14985cb9/#bar BarInstance BarShape BarTree
---- 180dda0b...c4f8c4dc/#bar BarInstance BarShape BarTree
-- 3c9c9cff...fc7f916b/#registration DataRegistration DataRegistrationShape DataRegistrationTree, BazContainingTree
---- 4376595a...f8d2547c/#baz BazInstance BazShape BazTree
---- 14c9fc6a...7f6de3ca/#baz BazInstance BazShape BazTree

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.

Intersecting shape trees for a Data Registration and the shape tree registered with it
-- 8501f084-deb9-4775-8a35-2040df435d21/#registration
Contents of the Data Registration
<#registration>
  a interop:DataRegistration ;
  interop:registeredBy <https://alice.pod.example/profile/id#me> ;
  interop:registeredWith <https://app.example/id#agent> ;
  interop:registeredAt "2020-04-04T20:15:47.000Z"^^xsd:dateTime ;
  interop:updatedAt "2020-04-04T21:11:33.000Z"^^xsd:dateTime ;
  interop:registeredShapeTree foo:fooTree ;
  interop:registeredType foo:fooThing .
Ensure the container resource for the Data Registration conforms to interops#DataRegistrationShape.
<#DataRegistrationTree>
  a st:ShapeTree;
  st:expectsType st:ShapeTreeContainer ;
  st:validatedBy <interops#DataRegistrationShape> .

And also ensure the Data Registration only contains resources that conform to <#FooTree>.

<#FooContainingTree>
  a st:ShapeTree;
  st:expectsType st:ShapeTreeContainer ;
  st:contains <#FooTree> .
------ 16e1eae9-20a5-489d-8380-8c07ca3805c4#foo
Contents of the Data Instance
<#foo>
  a foo:fooThing ;
  foo:isExample "of an instance" .
Ensure the resource for the Data Instance conforms to <#FooTree>.
<#FooTree>
  a st:ShapeTree;
  st:expectsType st:ShapeTreeResource ;
  st:validatedBy <foo#FooShape> .

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.

Permission model for Data Registry resources.
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.

Modes of access for a Data Registration
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.

Modes of access for a Specific Data Instance
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:

The following operations allow for the lookup, creation, and deletion of Data Registrations and Data Instances in a Data Registry.

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
  1. MUST return 404 if TREE or REGISTRY cannot be successfully dereferenced.

  2. For each Data Registration REGISTRATION included in REGISTRY hasRegistration

    1. return REGISTRATION if REGISTRATION 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
  1. MUST return 404 if TREE or REGISTRY cannot be successfully dereferenced.

  2. MUST return 400 if an existing Data Registration is returned from § 5.5.1 Load Data Registration with inputs: TREE, REGISTRY

  3. Let REG be a newly initialized Data Registration

  4. Let REG registeredBy be the current Agent

  5. Let REG registeredWith be the identity of the Application executing the operation

  6. Let REG registeredAt be the current date and time

  7. Let REG updatedAt be the current date and time

  8. Let REG registeredShapeTree be TREE

  9. Let REG registeredType be TYPE if TYPE is not empty

  10. PUT REG into the REGISTRY container

    1. A UUID MUST be assigned as the resource name.

    2. Plant TREE with REG as the Target Container.

  11. Assign permissions for REG per the § 5.4 Permission Model

  12. Link REG to REGISTRY via REGISTRY hasRegistration

  13. 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
  1. PUT INSTANCE into the REGISTRATION container

    1. A UUID MUST be assigned as the resource name.

    2. A target shape tree MUST be assigned via the rel=http://shapetrees.org/#targetShapeTree HTTP Link relation

    3. A focus node for shape tree validation MUST be assigned via the rel=http://shapetrees.org/#FocusNode HTTP Link relation

  2. 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
  1. MUST return 404 if REGISTRATION cannot be successfully dereferenced.

  2. MUST return 400 if REGISTRATION contains one or more Data Instances.

  3. Remove REGISTRATION from the graph of REGISTRY via REGISTRY hasRegistration

  4. 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
  1. MUST return 404 if INSTANCE cannot be successfully dereferenced.

  2. If INSTANCE is a container

    1. Let RESOURCES be a hierarchy of all resources contained by INSTANCE, including any child containers and resources.

    2. DELETE each RESOURCE in RESOURCES, iterating up from the bottom of the RESOURCES hierarchy

  3. 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.

6.2. Workflows

The following workflows represent the authorization patterns enabled by this specification.

6.2.1. Presenting an Access Grant

Description
This workflow details how an Access Grant is presented to a given Agent for data in their control, based on the Access Need Groups associated.

Each Access Grant is associated with a specific Access Grant Subject, and one or more Access Need Groups. The Access Grant Subject may be another Agent, an Agent using an Application, or an Application operating as an Agent.

Access Grant presentation may be invoked from a number of workflows and contexts, including but not limited to § 6.2.2 Application Requests Access, § 6.2.3 Another Agent Requests Access, § 6.2.4 Controller Shares Access, and § 6.2.5 Controller Shares Access with Invited Agent.

This workflow is composed of several operations:

  1. § 6.2.1 Presenting an Access Grant

    1. § 6.2.1.1 Presenting an Access Need Group - Called for each Access Need Group

      1. § 6.2.1.2 Presenting a Data Access Need - Called for each Access Need in the Access Need Group

      2. § 6.2.1.3 Presenting a Trusted Need - Called for each Trusted Need in the Access Need Group

Inputs
SUBJECT This may be a tuple of Agent and Application in the case of a weakly identifiable application, or Application and Application in the case of a strongly identifiable application
NEEDGROUPS Access Need Groups to use when a new Access Grant is being initialized

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.

An example Access Grant for an Application.
  1. Let GRANT be an existing Access Grant for SUBJECT returned by § 8.4.6 Load Grant

    1. If GRANT is missing, create one via § 8.4.1 Initialize Grant

  2. Present information about the Application APP if the Access Grant Subject is for an Application:

    1. Application Name - APP applicationName

    2. Application Identity - APP URI

    3. Application Author Name - APP applicationAuthorName

    4. Application Author Identity - APP applicationAuthor

    5. Application Thumbnail - APP applicationThumbnail

    6. Application Summary - APP applicationDescription

  3. Present information about the Agent AGENT if the Access Grant Subject is not an Application

    1. Agent Name AGENT fullName

    2. Agent Identity - AGENT URI

  4. Call § 6.2.1.1 Presenting an Access Need Group for each Access Need Group linked via GRANT hasAccessNeedGroup.

  5. 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
Depicting an Access Need associated with a given Access Need Group, and several Referenced Access Needs linked to it. The controller chose to grant access to all instances now and in the future.
  1. Let GDEC be the Access Need Group Decorator linked via GROUP hasAccessNeedGroupDecorator

  2. Present information about the Access Need Group GROUP

    1. Group Name - GDEC skos:prefLabel

    2. Group Description - GDEC skos:definition

    3. Grantee Type - GROUP authenticatesAs

    4. Necessity - GROUP accessNecessity

  3. Allow GROUP to be disabled via § 8.4.22 Deny Access Need Group if group necessity is optional

  4. For each Access Need NEED linked via GROUP hasAccessNeed

    1. Call § 6.2.1.2 Presenting a Data Access Need

  5. For each Trusted Need TNEED linked via GROUP hasTrustedNeed

    1. Call § 6.2.1.3 Presenting a Trusted Need

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
Depicting an Access Need with two selected Data Instances, with access to the Referenced Access Needs set based on whether there is a link to the selected instances.
  1. Call § 6.2.1.2.1 Presenting Data Access Need Details to explain the Access Need

  2. Let DG be the Data Grant linked via NEED hasDataGrant

  3. Manage the scope of data to be granted DG scopeOfGrant:

    1. No Access - interop:NoAccess (if necessity is optional)

      1. Enable via § 8.4.23 Deny Data Grant

    2. All Current and Future - interop:AllInstances

      1. Enable via § 8.4.25 Select All Data Instances

    3. Only Selected Instances - interop:SelectedInstances

      1. Present existing Data Instances corresponding to DG registeredShapeTree, identifying any existing selections linked via DG hasDataInstance

      2. Allow one or more to be chosen

      3. Enable via § 8.4.27 Select Specific Data Instance, providing each selected Data Instance

  4. For each Referenced Access Need REFNEED linked via NEED hasReferencedAccessNeed

    1. Let REFDG be the Referenced Data Grant linked via NEED hasReferencedDataGrant

    2. Call § 6.2.1.2.1 Presenting Data Access Need Details to explain the Referenced Access Need

      1. Manage the scope of data to be granted REFDG scopeOfGrant:

        1. No Access - interop:NoAccess (if necessity is optional)

          1. Enable via § 8.4.24 Deny Referenced Data Grant

        2. All Current and Future - interop:AllInstances

          1. Enable via § 8.4.26 Select All Referenced Data Instances

        3. Only Inherited Instances - interop:InheritInstances (if DG scopeOfGrant is interop:SelectedInstances)

          1. Present Data Instances of REFNEED registeredShapeTree linked to all Data Instances for DG via st:traverseViaShapePath of DG registeredShapeTree

        4. Only Selected Instances - interop:SelectedInstances

          1. Present existing Data Instances corresponding to REFDG registeredShapeTree, identifying any existing selections linked via REFDG hasDataInstance

          2. Allow one or more to be chosen

          3. 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:

  1. Let RDG be the Remote Data Grant linked via NEED hasRemoteDataGrant

  2. Manage the scope of data to be granted RDG scopeOfGrant:

    1. No Access - interop:NoAccess (if necessity is optional)

      1. Enable via § 8.4.36 Deny Remote Data Grant

    2. All Remote Data - interop:AllRemote

      1. Enable via § 8.4.30 Select All Remote Instances

    3. All Remote From Agent - interop:AllRemoteFromAgent

      1. Present existing Remote Agent Data Registrations corresponding to NEED registeredShapeTree, identifying any existing selections linked via RDG hasRemoteDataFromAgent

      2. Allow one or more to be chosen

      3. Enable via § 8.4.32 Select All Remote From Agent

    4. Only Selected Remote Data - interop:SelectedRemote

      1. 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 via RDG hasDataGrant and/or RDG:hasReferencedDataGrant

      2. Allow one or more to be chosen

      3. Enable via § 8.4.34 Select Specific Remote Agent Data Grants, providing the selected Data Grants and/or Referenced Data Grants.

  3. For each Referenced Access Need REFNEED linked via NEED hasReferencedAccessNeed

    1. Let REFRDG be the Referenced Remote Data Grant linked via NEED hasReferencedRemoteDataGrant

    2. Manage the scope of data to be granted REFRDG scopeOfGrant:

      1. No Access - interop:NoAccess (if necessity is optional)

        1. Enable via § 8.4.37 Deny Referenced Remote Data Grant

      2. All Remote Data - interop:AllRemote

        1. Enable via § 8.4.31 Select All Referenced Remote Instances

      3. All Remote From Agent - interop:AllRemoteFromAgent

        1. Present existing Remote Agent Data Registrations corresponding to NEED registeredShapeTree, identifying any existing selections linked via REFRDG hasRemoteDataFromAgent

        2. Allow one or more to be chosen

        3. Enable via § 8.4.33 Select All Referenced Remote From Agent

      4. Only Selected Remote Data - interop:SelectedRemote

        1. 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 via REFRDG hasDataGrant and/or REFRDG hasReferencedDataGrant

        2. Allow one or more to be chosen

        3. 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
  1. Let STDEC be the Shape Tree Decorator linked via NEED hasShapeTreeDecorator

  2. Let ANDEC be the Access Need Decorator linked via NEED hasAccessNeedDecorator

  3. Present information about the Access Need:

    1. Shape Tree Name - STDEC skos:prefLabel

    2. Shape Tree Description - STDEC skos:definition

    3. Access Modes - NEED accessModes

    4. 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
Depicting Trusted Needs for an Application that will be used as an authorization agent, requiring elevated access across the board.
  1. Let TNEED be the Access Need Decorator linked via TNEED hasAccessNeedDecorator

  2. Let TG be the Trusted Grant linked via TNEED hasTrustedGrant

  3. Present information about the Trusted Need:

    1. Trusted Need Type - STDEC skos:prefLabel

    2. Trusted Need Description - STDEC skos:definition

    3. Access Modes - TNEED accessModes

    4. Necessity - TNEED accessNecessity

  4. Manage the scope of the trusted grant TG scopeOfGrant:

    1. Next if TNEED trustedWithType is interop:Agent

    2. All Registries - where rdf:type of Registry is TNEED trustedWithType

      1. Enable via § 8.4.38 Select Trusted Registry Set

    3. Specific TYPE Registries

      1. Present existing Registries where rdf:type is TNEED trustedWithType

      2. Allow one or more Registries to be chosen

      3. 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.

  1. CONTROLLER decides they’d like to use APP

  2. CONTROLLER provides their identity to APP

  3. APP dereferences the identity to get CONTROLLER's identity profile document.

  4. APP discovers that AUTHZ is an Application that is a Trusted Agent of CONTROLLER for data authorization via the § 3.5.1 Load Application Service operation.

  5. APP redirects CONTROLLER to AUTHZ via the § 3.5.2 Redirect to Application Service operation.

    1. Let APPREG be an Application Registration returned by § 4.5.1 Load Application Registration with inputs: CONTROLLER, APP

    2. If APPREG is empty let APPREG be the Application Registration returned by § 4.5.2 Register Application with inputs: AGENT, APP, REGISTRY.

    3. AUTHZ looks in APP's application profile document for Access Need Groups with an interop:accessScenario of interop:PersonalAccess

    4. Any Access Need Groups found are passed to the § 6.2.1 Presenting an Access Grant workflow, which presents them to CONTROLLER.

    5. CONTROLLER decides whether to grant APP the access requested.

    6. CONTROLLER authorizes the requested Access Need Groups and Access Needs:

      1. The § 8.4.8 Record Grant operation is invoked

        1. An Access Grant is stored in CONTROLLER's Access Grant Registry.

        2. § 8.4.12 Apply Permissions is called to apply permissions based on the Access Grant.

        3. § 9.4.1 Provide Access Receipt is called to store the Access Receipt. The Application has set interop:receivesAccessReceipt to ReceiptInRegistration, so the Access Receipt is stored in the Application Registration for APP.

    7. AUTHZ redirects CONTROLLER back to APP 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.

  1. REQUESTER would like access to CONTROLLER's data.

  2. REQUESTER provides CONTROLLER's identity to REQAPP.

  3. REQAPP dereferences CONTROLLER's identity to get CONTROLLER's identity profile document.

  4. REQAPP uses Access Need Groups from its application profile document with an interop:accessScenario of interop:SharedAccess to identify Access Need Groups to request from CONTROLLER.

  5. CONTROLLER has an interop:receivesAccessReceipt value of ReceiptInMessage in their identity profile document.

  6. REQAPP puts the Access Need Groups into an Access Request and posts it to the access inbox identified by interop:hasAccessInbox in the CONTROLLER's identity profile document.

  7. CAUTHZ monitors CONTROLLER's access inbox autonomously. It notifies CONTROLLER when a new Access Request is received.

    1. CONTROLLER clicks a link in the notification from CAUTHZ, opening the CAUTHZ user interface and invoking the [[##present-grant]] workflow using the Access Need Groups from the Access Request.

    2. CONTROLLER determines whether they wish to grant the access requested.

    3. Assuming CONTROLLER authorizes a minimum of the required Access Need Groups and Access Needs, the § 8.4.8 Record Grant operation is invoked.

    4. § 8.4.8 Record Grant stores an Access Grant in CONTROLLER's Access Grant Registry.

      1. § 8.4.12 Apply Permissions is called to apply permissions based on the Access Grant.

      2. § 9.4.1 Provide Access Receipt is called to deliver the Access Receipt.

        1. CAUTHZ dereferences REQUESTER's identity to get REQUESTER's identity profile document.

        2. REQUESTER has set interop:receivesAccessReceipt to ReceiptInMessage, so the Access Receipt is posted to the access inbox identified via hasAccessInbox in REQUESTER's 'identity profile document.

  8. RAUTHZ monitors REQUESTER's access inbox autonomously. It notifies REQUESTER when a new Access Receipt is received.

    1. REQUESTER clicks the link in the notification, opening the RAUTHZ user interface, and presenting the Access Receipt to REQUESTER.

    2. REQUESTER accepts the Access Receipt, and RAUTHZ invokes the § 9.4.4 Record Access Receipt operation.

      1. § 9.4.4 Record Access Receipt is called to store the Access Receipt in REQUESTER's Access Receipt Registry.

      2. § 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.

  1. CONTROLLER would like to give RECEIVER access to their data.

  2. CONTROLLER provides RECEIVER's identity to CAPP.

  3. CAPP dereferences RECEIVER's identity to get RECEIVER's identity profile document.

  4. CAPP discovers that CAUTHZ is an Application that is a Trusted Agent of CONTROLLER for data authorization via the § 3.5.1 Load Application Service operation.

  5. CAPP redirects CONTROLLER to CAUTHZ via the § 3.5.2 Redirect to Application Service operation.

    1. CAUTHZ looks in CAPP's application profile document for Access Need Groups with an interop:accessScenario of interop:SharedAccess

    2. Any Access Need Groups found are passed to the [[##present-grant]] workflow, which presents them to CONTROLLER.

    3. CONTROLLER authorizes the data to share with RECEIVER based on the provided Access Need Groups.

      1. The § 8.4.8 Record Grant operation is invoked

        1. An Access Grant is stored in CONTROLLER's Access Grant Registry.

        2. § 8.4.12 Apply Permissions is called to apply permissions based on the Access Grant.

        3. § 9.4.1 Provide Access Receipt is called to store the Access Receipt. RECEIVER has set interop:receivesAccessReceipt to ReceiptInMessage, so the Access Receipt is posted to the access inbox identified via hasAccessInbox in RECEIVER's 'identity profile document.

    4. CAUTHZ redirects CONTROLLER back to CAPP via the § 3.5.3 Return from Application Service operation.

  6. RAUTHZ monitors RECEIVER's access inbox autonomously. It notifies RECEIVER when a new Access Receipt is received.

    1. RECEIVER clicks the link in the notification, opening the RAUTHZ user interface to review the Access Receipt.

    2. RECEIVER accepts the Access Receipt, and RAUTHZ invokes the § 9.4.4 Record Access Receipt operation.

      1. § 9.4.4 Record Access Receipt is called to store the Access Receipt in RECEIVER's Access Receipt Registry.

      2. § 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 INVITEEs.

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.

  1. CONTROLLER would like to give INVITEE access to their data.

  2. CONTROLLER provides INVITEE's e-mail address and mobile number to CAPP.

  3. CAPP discovers that CAUTHZ is an Application that is a Trusted Agent of CONTROLLER for data authorization via the § 3.5.1 Load Application Service operation.

  4. CAPP redirects CONTROLLER to CAUTHZ via the § 3.5.2 Redirect to Application Service operation.

    1. CAUTHZ looks in CAPP's application profile document for Access Need Groups with an interop:accessScenario of interop:SharedAccess

    2. Any Access Need Groups found are passed to the [[##present-grant]] workflow, which presents them to CONTROLLER.

    3. CONTROLLER authorizes the data to share with INVITEE based on the provided Access Need Groups.

      1. The § 8.4.9 Record Invitation operation is invoked

        1. An Access Invitation is stored in CONTROLLER's Access Grant Registry.

        2. § 8.4.10 Deliver Invitation is called to create an invitation entry for each Access Invitation Channel in the Access Invitation with CISERVICE

        3. For each Access Invitation Channel in the Access Invitation

          1. CISERVICE sends a notification to INIVITEE using the medium associated with the Access Invitation Channel type

    4. CAUTHZ redirects CONTROLLER back to CAPP via the § 3.5.3 Return from Application Service operation.

  5. INVITEE receives a notification associated with one of the Access Invitation Channels.

    1. INVITEE clicks a link in the notification to register an identity and pod with PROVIDER.

    2. INVITEE clicks a link in the notification bringing them to the CISERVICE user interface to validate the invitation by invoking § 8.4.11 Validate Invitation.

      1. 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.

      2. CISERVICE initializes a new Access Grant via § 8.4.1 Initialize Grant, using the contents of the Access Invitation, and the new registered identity for INVITEE.

      3. CISERVICE calls § 8.4.8 Record Grant using the Access Grant initialized from the Access Invitation

        1. An Access Grant is stored in CONTROLLER's Access Grant Registry.

        2. § 8.4.12 Apply Permissions is called to apply permissions based on the Access Grant.

        3. § 9.4.1 Provide Access Receipt is called to store the Access Receipt. INVITEE has set interop:receivesAccessReceipt to ReceiptInMessage, so the Access Receipt is posted to the access inbox identified via hasAccessInbox in INVITEE'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 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.

An example Access Need Group
<#ng-project-management>
  a interop:AccessNeedGroup ;
  interop:accessNecessity interop:accessRequired ;
  interop:accessScenario interop:PersonalAccess ;
  interop:authenticatesAs interop:Pilot ;
  interop:hasAccessDecoratorIndex nn:index
  interop:hasAccessNeed <#need-project> .
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.

An example Access Need
<#need-project>
    a interop:AccessNeed ;
    interop:inAccessNeedGroup <#need-group-pm> ;
    interop:registeredShapeTree pm:ProjectTree ;        
    interop:hasAccessNeedDecorator nn-index:projectDecorator
    interop:accessNecessity interop:accessRequired ;
    interop:accessMode acl:read, acl:write, acl:Control ;        
    interop:hasReferencedAccessNeed 
        <#need-issue>, <#need-task>, <#need-release>, <#need-document> ;
    interop:hasDataGrant <#data-grant-project> ;
    interop:hasRemoteDataGrant <#remote-data-grant-project> .  
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.

An example Referenced Access Need linked from the prior example of an Access Need
<#need-issue>
    a interop:ReferencedAccessNeed ;
    interop:hasAccessNeed <#need-project> ;
    interop:hasAccessNeedDecorator nn-index:issueDecorator ;
    interop:registeredShapeTree pm:IssueTree ;        
    interop:accessNecessity interop:accessRequired ;    
    interop:accessMode acl:read, acl:write, acl:Control ;
    interop:hasReferencedDataGrant <#data-grant-issue> ;
    interop:hasReferencedRemoteDataGrant <#remote-data-grant-issue> .
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>+
}
An Access Request sent from one agent to another
@prefix interop: <http://www.w3.org/ns/solid/interop#> .
@prefix note: <http://shapetrees.pub/ns/note#> .

<> a interop:AccessRequest ;
  interop:fromAgent https://alice.pod.example/profile/id#me ;
  interop:toAgent https://bob.pod.example/profile/id#me ;
  interop:hasAccessNeedGroup <#notebook-collaboration-group> .

<#need-group-photos>
  a interop:AccessNeedGroup ;    
  interop:hasAccessDecoratorIndex photoapp-index ;    
  interop:accessNecessity interop:accessRequired ;
  interop:accessScenario interop:SharedAccess ;
  interop:authenticatesAs interop:Agent ;    
  interop:hasAccessNeed <#need-photo-album> .

<#need-photo-album>
    a interop:AccessNeed ;
    interop:inAccessNeedGroup <#need-group-photos> ;
    interop:registeredShapeTree photo:PhotoAlbumTree ;        
    interop:accessNecessity interop:accessRequired ;
    interop:accessMode acl:read ;    
    interop:hasReferencedAccessNeed <#need-photo> .

<#need-photo>
    a interop:ReferencedAccessNeed ;
    interop:inAccessNeedGroup <#need-group-photos> ;
    interop:registeredShapeTree photo:PhotoTree ;        
    interop:accessNecessity interop:accessRequired ;    
    interop:accessMode acl:read .

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+ ;
}
Access Decorator Index document linked by the #notebook-collaboration-group
@prefix interop: <http://www.w3.org/ns/solid/interop#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<>
  a interop:AccessDecoratorIndex ;
  interop:defaultLanguage "en"^^xsd:language ;
  interop:hasSeries <#series-en> .

<#series-en>
    a interop:AccessDecoratorSeries ;
    interop:usesLanguage "en"^^xsd:language ;
    interop:hasVersion <#en-v10>, <#en-v11> .

<#en-v10>
    a interop:AccessDecoratorVersion ;
    interop:isVersion "1.0.0" ;
    interop:hasSHA256 "98198123981273981273918273912738" ;
    interop:hasAccessDecoratorResource <notebook-decorator-en-1.0> .

<#en-v11>
    a interop:AccessDecoratorVersion ;
    interop:isVersion "1.1.0" ;
    interop:hasSHA256 "12312312371273712731872371273712" ;
    interop:hasAccessDecoratorResource <notebook-decorator-en-1.1> .
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
  1. Let USESERIES be INDEX defaultSeries

  2. Let USEVERSION be an unassigned Access Decorator Version

  3. For each Access Decorator Series SERIES in INDEX

    1. Let USESERIES be SERIES if SERIES usesLanguage == LANG

  4. MUST return a status code of 404 if no Access Decorator Series are found.

  5. For each Access Decorator Version VERSION in USESERIES hasVersion

    1. Let USEVERSION be VERSION if VERSION is a more recent semantic version than USEVERSION or if USEVERSION is unassigned.

  6. MUST return a status code of 404 if no Access Decorator Versions are found.

  7. Let DECR be the Access Decorator Resource linked from USEVERSION hasAccessDecoratorResource

  8. MUST return a status code of 404 if DECR is unassigned.

  9. 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
  1. Let DECR be the Access Decorator Resource returned by § 7.3.2 Get Access Need Group Decorator with inputs: GROUP hasAccessDecoratorIndex, LANG

  2. Let USEGDEC be an unassigned Access Need Group Decorator

  3. Let GDECS be all Access Need Group Decorators in DECR

  4. For each [=Acces Need Group Decorator] GDEC in GDECS

  5. Let USEGDEC be GDEC if GDEC hasAccessNeedGroup is GROUP

  6. MUST return a status code of 404 if USEGDEC is unassigned

  7. 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
  1. Let GROUP be NEED inAccessNeedGroup

  2. Let DECR be the Access Decorator Resource returned by § 7.3.2 Get Access Need Group Decorator with inputs: GROUP hasAccessDecoratorIndex, LANG

  3. Let USENDEC be an unassigned Access Need Decorator

  4. Let NDECS be all Access Need Decorators in DECR

  5. For each [=Acces Need Decorator] NDEC in NDECS

  6. Let USENDEC be NDEC if NDEC hasAccessNeedGroup is GROUP and NDEC registeredShapeTree is NEED registeredShapeTree

  7. MUST return a status code of 404 if USENDEC is unassigned

  8. 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:

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

Data model for the Access Grant Registry

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.

An Access Grant Registry Set at https://alice.pod.example/profile/grant#set linking to two different Access Grant Registries
<#set>
  a interop:AccessGrantRegistrySet;
  interop:hasRegistry <https://alice.pod.example/grants/#registry> ,
                  <https://alice.otherpod.example/grants/#registry> .
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.

An Access Grant Registry at https://alice.pod.example/grants/#registry linking to several registered Access Grants or Access Invitations
<#registry>
  a interop:AccessGrantRegistry ;
  interop:hasRegistration 
    <ab3d0023-3860-4358-ae33-8d3af1097b9d#grant> ,
    <ad7b935f-ced9-4ce6-835f-5c6abc046228#grant> ,
    <5ed73c65-ce77-4c8a-8f7e-9715b90307e6#grant> ,
    <2d575cba-3f6c-4c58-bccd-0e6266ba56cf#invitation> .
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.

An Access Grant at https://alice.pod.example/grants/ab3d0023-3860-4358-ae33-8d3af1097b9d#grant
<#grant>
  a interop:AccessGrant ;
  interop:registeredBy <https://alice.pod.example/profile/id#me> ;
  interop:registeredWith <https://trusted.example/id#agent> ;
  interop:registeredAt "2020-09-05T06:15:01Z"^^xsd:dateTime ;
  interop:updatedAt "2020-09-05T06:15:01Z"^^xsd:dateTime ;
  interop:hasAccessGrantSubject <#grant-subject> ;
  interop:hasAccessNeedGroup <#need-group-pm> ;    
  interop:hasDataGrant <#data-grant-project> ;
  interop:hasRemoteDataGrant <#remote-data-grant-project> .
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.

An Access Grant Subject at https://alice.pod.example/grants/ab3d0023-3860-4358-ae33-8d3af1097b9d#grant-subject
<#grant-subject>
    a interop:AccessGrantSubject ;
    interop:accessByAgent <https://alice.pod.example/profile/id#me> ;
    interop:accessByApplication <https://acmeproject.example/profile/id#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:

When recording a Data Grant via § 8.4.8 Record Grant:

An Data Grant at https://alice.pod.example/grants/ab3d0023-3860-4358-ae33-8d3af1097b9d#data-grant-project
<#data-grant-project>
    a interop:DataGrant ;
    interop:hasAccessGrant <#grant> ;
    interop:satisfiesAccessNeed <#need-project> ;    
    interop:registeredShapeTree pm:ProjectTree ;        
    interop:hasDataRegistration data:project-tree-reg ;
    interop:accessMode acl:read, acl:write, acl:Control ;
    # Scope grants access to all instances in the project
    # data registration, now and in the future, with no conditions
    interop:scopeOfGrant interop:AllInstances ;    
    interop:hasReferencedDataGrant
        <#data-grant-issue> ,  
        <#data-grant-task> , 
        <#data-grant-release> ,
        <#data-grant-document> .
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
  • interop:AllInstances - Scope includes access to all Data Instances of the associated Data Registration
  • interop:SelectedInstances - Scope includes access only to those Data Instances specifically selected by the Agent
  • interop:NoAccess - No access is granted
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:

When recording a Referenced Data Grant via § 8.4.8 Record Grant:

An Referenced Data Grant at https://alice.pod.example/grants/ab3d0023-3860-4358-ae33-8d3af1097b9d#data-grant-issue
<#data-grant-issue>
  a interop:ReferencedDataGrant ;
  interop:hasDataGrant <#data-grant-project> ;
  interop:satisfiesAccessNeed <#need-issue> ;        
  interop:registeredShapeTree pm:IssueTree ;    
  interop:hasDataRegistration data:issue-tree-reg ;
  interop:accessMode acl:read, acl:write, acl:Control ;    
  interop:scopeOfGrant interop:AllInstances .
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
  • interop:AllInstances - Scope includes access to all Data Instances of the associated Data Registration
  • interop:SelectedInstances - Scope includes access only to those Data Instances specifically selected by the Agent
  • interop:InheritInstances - Scope includes access to Data Instances inherited by instances selected in the parent Data Grant
  • interop:NoAccess - No access is granted
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:

When recording a Remote Data Grant via § 8.4.8 Record Grant:

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:

When recording a Referenced Remote Data Grant via § 8.4.8 Record Grant:

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:

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
  • interop:Agent
  • interop:ApplicationRegistrySet
  • interop:DataRegistrySet
  • interop:AccessGrantRegistrySet
  • interop:AccessReceiptRegistrySet
  • interop:RemoteDataRegistrySet
  • interop:ApplicationRegistry
  • interop:DataRegistry
  • interop:AccessGrantRegistry
  • interop:AccessReceiptRegistry
  • interop:RemoteDataRegistry
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.

An Access Invitation at https://alice.pod.example/grants/08c5ae76-6c83-46f8-8e1d-eb14219e7f5f#invitation
<#invitation>
  a interop:AccessInvitation ;
  interop:registeredBy https://alice.pod.example/profile/id#me ;
  interop:registeredWith https://trusted.example/id#agent ;
  interop:registeredAt "2020-09-13T19:32:52Z"^^xsd:dateTime ;
  interop:updatedAt "2020-09-13T19:32:52Z"^^xsd:dateTime ;
  interop:expiresAt "2020-09-20T19:32:52Z"^^xsd:dateTime ;
  interop:hasAccessNeedGroup <#need-group-pm> ;
  interop:hasDataGrant <#data-grant-project> ;
  interop:hasAccessInvitationChannel 
    <#phone-channel> , 
    <#email-channel> .
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.

Example Access Invitation Channels
<#phone-channel>
  a interop:PhoneInvitationChannel ;
  interop:channelTarget "(555) 555-1212" ;
  interop:channelCode "654345" ;
  interop:isValidated false ;
  interop:remainingAttempts 3 .

<#email-channel>
  a interop:EmailInvitationChannel ;
  interop:channelTarget "bob@example.com" ;
  interop:channelCode "434567" ;
  interop:isValidated true ;
  interop:remainingAttempts 3 .
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   # E-mail
  :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

Each Access Grant or Access Invitation will have some combination of Data Grants, Remote Data Grants, and/or Trusted Grants:

Record Access Grants and Access Invitations:

Apply permissions based on the composition of an Access Grant:

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
  1. Let GRANT be a newly initialized Access Grant

  2. Let GRANT hasAccessGrantSubject be SUBJECT

  3. For each Access Need Group GROUP in GROUPS

    1. Link GROUP to GRANT via GRANT hasAccessNeedGroup

  4. For each Access Need Group GROUP linked via GRANT hasAccessNeedGroup

    1. For each Access Need NEED in GROUP

      1. Call § 8.4.3 Initialize Data Grant with inputs: NEED

      2. Call § 8.4.4 Initialize Remote Data Grant with inputs: NEED

    2. For each Trusted Need TNEED in GROUP

      1. Call § 8.4.5 Initialize Trusted Grant with inputs: TNEED

  5. 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
  1. Let INVITE be a newly initialized Access Invitation

  2. For each Access Invitation Channel ICHANNEL in ICHANNELS

    1. Let ICHANNEL be linked to INVITE via INVITE hasAccessInvitationChannel

  3. For each Access Need Group GROUP in GROUPS

    1. Link GROUP to INVITE via INVITE hasAccessNeedGroup

  4. For each Access Need Group GROUP linked via INVITE hasAccessNeedGroup

    1. For each Access Need NEED in GROUP

      1. Call § 8.4.3 Initialize Data Grant with inputs: NEED, GRANT

      2. Call § 8.4.4 Initialize Remote Data Grant with inputs: NEED, GRANT

    2. For each Trusted Need TNEED in GROUP

      1. Call § 8.4.5 Initialize Trusted Grant with inputs: TNEED, GRANT

  5. 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 NEED has any Referenced Access Needs.

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
  1. Let DG be a newly initialized Data Grant

  2. Let DG hasAccessGrant be GRANT

  3. Let DG satisfiesAccessNeed be NEED

  4. Let DG registeredShapeTree be NEED registeredShapeTree

  5. Let DG hasRegistration be a Data Registration DR where DR registeredShapeTree == DG registeredShapeTree

  6. Let DG accessmodes be CACCESS accessmodes

  7. Let DG scopeOGrant be interop:NoAccess

  8. Let NEED hasDataGrant be DG

  9. For each Referenced Access Need REFNEED linked via NEED hasReferencedAccessNeed

    1. Let REFDG be a newly initialized Referenced Data Grant

    2. Let REFDG hasDataGrant be DG

    3. Let REFDG satisfiesAccessNeed be REFNEED

    4. Let REFDG registeredShapeTree be REFNEED registeredShapeTree

    5. Let REFDG hasRegistration be a Data Registration DR where DR registeredShapeTree == REFDG registeredShapeTree

    6. Let REFDG accessModes be REFNEED accessModes

    7. Let REFDG scopeOfGrant be interop:NoAccess

    8. Link REFDG to DG via DG hasReferencedDataGrant

  10. 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 NEED has any Referenced Access Needs.

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
  1. Let RDG be a newly initialized Remote Data Grant

  2. Let RDG hasAccessGrant be GRANT

  3. Let RDG satisfiesAccessNeed be NEED

  4. Let RDG registeredShapeTree be NEED registeredShapeTree

  5. Let RDG accessmodes be NEED accessmodes

  6. Let RDG scopeOfGrant be interop:NoAccess

  7. Let NEED hasRemoteDataGrant be RDG

  8. For each Referenced Access Need REFNEED linked via NEED hasReferencedAccessNeed

    1. Let REFRDG be a newly initialized Referenced Remote Data Grant

    2. Let REFRDG hasRemoteDataGrant be RDG

    3. Let REFRDG satisfiesAccessNeed be REFNEED

    4. Let REFRDG registeredShapeTree be REFNEED registeredShapeTree

    5. Let REFRDG hasRegistration be a Data Registration DR where DR registeredShapeTree == REFRDG registeredShapeTree

    6. Let REFRDG accessModes be REFNEED accessModes

    7. Let REFRDG scopeOfGrant be interop:NoAccess

    8. Link REFRDG to RDG via RDG hasReferencedRemoteDataGrant

  9. 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
  1. Let TG be a newly initialized Trusted Grant

  2. Let TG hasAccessGrant be GRANT

  3. Let TG satisfiesTrustedNeed be TNEED

  4. Let TG trustedWith be interop:NoAccess

  5. Let TG scopeOfGrant be interop:NoAccess

  6. Let TG trustedWithType be TNEED trustedWithType

  7. Let TG accessmodes be TNEED accessmodes

  8. Let TNEED hasTrustedGrant be TG

  9. 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
  1. For each Access Grant GRANT included in REGISTRY hasRegistration

    1. return GRANT if GRANT 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
  1. Let INVITATIONS be an empty set of Access Invitations

  2. For each Access Invitation INVITATION linked via REGISTRY hasRegistration

    1. For each Access Invitation Channel ICHANNEL linked via INVITATION hasAccessInvitationChannel

      1. Next if ICHANNEL channelTarget != TARGET

      2. Next if CODE is not empty and ICHANNEL channelCode != CODE

      3. Add INVITATION to INVITATIONS

  3. 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
  1. Add or Update GRANT resource in the REGISTRY container, conforming to the assigned interopt:AccessGrantTree.

  2. Link GRANT to the REGISTRY via REGISTRY hasRegistration if it has not already been added

  3. Call § 8.4.12 Apply Permissions with inputs: GRANT

  4. Call § 9.4.1 Provide Access Receipt with inputs: GRANT

  5. 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
  1. Add or Update INVITATION resource in the REGISTRY container, conforming to the assigned interopt:AccessInvitationTree

  2. Link INVITATION to the REGISTRY via ACCESS hasRegistration if it has not already been added

  3. Call § 8.4.10 Deliver Invitation with inputs: INVITATION

  4. 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
  1. Call § 8.4.13 Apply Data Permissions with inputs: GRANT

  2. Call § 8.4.16 Apply Remote Data Permissions with inputs: GRANT

  3. Call § 8.4.18 Apply Trusted Permissions with inputs: GRANT

  4. 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 GRANT hasDataGrant, including following any Referenced Data Grants.

All Data Grants and Referenced Data Grants are added to a hash map DRHASH. The key is the Data Registration associated with each Data Grant or Referenced Data Grant via hasDataRegistration.

The end result is the keys of DRHASH are a unique set of Data Registrations affected by GRANT, and each key has an array of related Data Grants and Referenced Data Grants as its value.

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
  1. 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.

  2. For each Data Grant DG linked via GRANT hasDataGrant

    1. Let DRKEY be DG hasDataRegistration added or found in DRHASH

    2. Add DG to the value array for DRKEY if missing

    3. For each Referenced Data Grant REFDG linked via DG hasReferencedDataGrant

      1. Let REFDRKEY be REFDG hasDataRegistration added or found in DRHASH

      2. Add REFDG to the array for REFDRKEY if missing

  3. For each Data Registration DR in DRHASH

    1. Call § 8.4.14 Apply Data Registration Permissions with inputs: DR, DRHASH[DR], GRANT

  4. 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 interop:scopeOfGrant values as keys. Each Data Grant or Referenced Data Grant with that scope will update the associated value.

  • interop:AllInstances - An array of interop:accessMode values

  • interop:SelectedInstances - A hash map with Data Instance as key and an array of interop:accessMode values

  • interop:InheritInstances - A hash map with the parent Data Instance as key and an array of interop:accessMode values

  • interop:NoAccess - Boolean true or false

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
  1. Let SUBJECT be the Access Grant Subject linked via GRANT hasAccessGrantSubject

  2. Call § 8.4.21 Remove Resource Permissions with inputs: DR, SUBJECT

  3. For each Data Instance DI linked via DR ldp:hasMember

    1. Call § 8.4.21 Remove Resource Permissions with inputs: DI, SUBJECT

  4. Let SCOPEHASH be a hash map with keys: interop:AllInstances, interop:SelectedInstances, interop:InheritInstances, interop:NoAccess

  5. Let SCOPEHASH[interop:SelectedInstances] be an empty hash map where Data Instances are keys with an array of interop:AccessModes as values

  6. Let SCOPEHASH[interop:InheritInstances] be an empty hash map where parent Data Instances are keys with an array of interop:AccessModes as values

  7. For each Data Grant or Referenced Data Grant DATAGRANT in DATAGRANTS

    1. If DATAGRANT scopeOfGrant is interop:AllInstances

      1. Let SCOPEHASH[interop:AllInstances] value be a union of current access modes and DATAGRANT accessModes

    2. If DATAGRANT scopeOfGrant is interop:NoAccess

      1. Let SCOPEHASH[interop:NoAccess] value be true

    3. If DATAGRANT scopeOfGrant is interop:SelectedInstances

      1. For each Data Instance DI linked via DATAGRANT hasDataInstance

        1. Let INSTKEY be Data Instance DI added or found in SCOPEHASH[interop:SelectedInstances][DI]

        2. Let SCOPEHASH[interop:SelectedInstances][DI] value be a union of current access modes and DATAGRANT accessModes

    4. If DATAGRANT scopeOfGrant is interop:InheritInstances

      1. Let PDG be the parent Data Grant linked via DATAGRANT hasDataGrant that the Referenced Data Grant inherits from.

      2. Error if PDG scopeOfGrant is not interop:SelectedInstances

      3. For each Data Instance DI linked via PDG hasDataInstance

        1. Let INSTKEY be Data Instance DI added or found in SCOPEHASH[interop:InheritInstances][DI]

        2. Let SCOPEHASH[interop:InheritInstances][DI] value be a union of current access modes and DATAGRANT accessModes

  8. If SCOPEHASH[interop:AllInstances] is not empty

    1. Call § 8.4.19 Apply Resource Permissions with inputs: DR, SUBJECT, MODES

  9. If SCOPEHASH[interop:InheritInstances] is not empty

    1. For each Data Instance DI in SCOPEHASH[interop:InheritInstances]

    2. Let REF be the Shape Tree Reference from calling § 8.4.15 Get Shape Tree Reference with inputs: DR registeredShapeTree, DI registeredShapeTree

    3. Let PRED be the rdf:property extracted from REF traverseViaShapePath

    4. Call § 8.4.20 Apply Conditional Resource Permissions with inputs: DR, SUBJECT, MODES, DI, PRED, NULL

  10. If SCOPEHASH[interop:SelectedInstances] is not empty

    1. For each Data Instance DI in SCOPEHASH[interop:SelectedInstances]

      1. 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
  1. For each Shape Tree Reference REF linked via REFERENCEDBY st:references

    1. Return REF if REF hasShapeTree is REFERENCED

  2. 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 GRANT hasRemoteDataGrant, including following any Referenced Remote Data Grants.

All Remote Data Grants and Referenced Remote Data Grants are added to a hash map RDRHASH. The key is the Remote Data Registration associated with each Remote Data Grant or Referenced Remote Data Grant via hasRemoteDataRegistration.

The end result is the keys of RDRHASH are a unique set of Remote Data Registrations affected by GRANT, and each key has an array of related Remote Data Grants and Referenced Remote Data Grants as its value.

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
  1. 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.

  2. For each Remote Data Grant RDG linked via GRANT hasRemoteDataGrant

    1. Let RDRKEY be RDG hasRemoteDataRegistration added or found in RDRHASH

    2. Add RDG to the value array for RDRKEY if missing

    3. For each Referenced Remote Data Grant REFRDG linked via RDG hasReferencedRemoteDataGrant

      1. Let REFRDRKEY be REFRDG hasRemoteDataRegistration added or found in RDRHASH

      2. Add REFRDG to the array for REFRDRKEY if missing

  3. For each Remote Data Registration RDR in RDRHASH

    1. Call § 8.4.17 Apply Remote Data Registration Permissions with inputs: RDR, RDRHASH[RDR], GRANT

  4. 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 interop:scopeOfGrant values as keys. Each Data Grant or Referenced Data Grant with that scope will update the associated value.

  • interop:AllRemote - An array of interop:accessMode values

  • interop:AllRemoteFromAgent - A hash map with Remote Agent Data Registration as key and an array of interop:accessMode values

  • interop:SelectedRemote - A hash map with Data Grant or Referenced Data Grant as key and an array of interop:accessMode values

  • interop:NoAccess - Boolean true or false

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
  1. Let SUBJECT be the Access Grant Subject linked via GRANT hasAccessGrantSubject

  2. Call § 8.4.21 Remove Resource Permissions with inputs: RDR, SUBJECT

  3. For each Remote Agent Data Registration RADR linked via RDR hasRemoteAgentDataRegistration

    1. Call § 8.4.21 Remove Resource Permissions with inputs: RADR, SUBJECT

    2. For each Data Grant or Referenced Data Grant DATAGRANT linked via RADR satisfiesDataGrant

      1. Call § 8.4.21 Remove Resource Permissions with inputs: DATAGRANT, SUBJECT

  4. Let SCOPEHASH be a hash map with keys: interop:AllRemote, interop:AllRemoteFromAgent, interop:SelectedRemote, interop:NoAccess

  5. Let SCOPEHASH[interop:AllRemoteFromAgent] be an empty hash map where Remote Agent Data Registrations are keys with an array of interop:AccessModes as values

  6. Let SCOPEHASH[interop:SelectedRemote] be an empty hash map where selected Data Grants or Referenced Data Grants are keys with an array of interop:AccessModes as values

  7. For each Remote Data Grant or Referenced Remote Data Grant REMOTEGRANT in REMOTEGRANTS

    1. If REMOTEGRANT scopeOfGrant is interop:AllRemote

      1. Let SCOPEHASH[interop:AllRemote] value be a union of current interop:accessModes and REMOTEGRANT accessModes

    2. If REMOTEGRANT scopeOfGrant is interop:NoAccess

      1. Let SCOPEHASH[interop:NoAccess] value be true

    3. If REMOTEGRANT scopeOfGrant is interop:AllRemoteFromAgent

      1. For each Remote Agent Data Registration RADR linked via REMOTEGRANT hasRemoteAgentDataRegistration

        1. Let RADRKEY be Remote Agent Data Registration RADR added or found in SCOPEHASH[interop:AllRemoteFromAgent][RADR]

        2. Let SCOPEHASH[interop:AllRemoteFromAgent][RADR] value be a union of current interop:accessModes and REMOTEGRANT accessModes

    4. If REMOTEGRANT scopeOfGrant is interop:SelectedRemote

      1. For each Data Grant or Referenced Data Grant DATAGRANT linked via REMOTEGRANT hasDataGrant or REMOTEGRANT hasReferencedDataGrant

        1. Let GRANTKEY be DATAGRANT added or found in SCOPEHASH[interop:SelectedRemote][DATAGRANT]

        2. Let SCOPEHASH[interop:SelectedRemote][DATAGRANT] value be a union of current interop:accessModes and REMOTEGRANT accessModes

  8. If SCOPEHASH[interop:AllRemote] is not empty

    1. Call § 8.4.19 Apply Resource Permissions with inputs: RDR, SUBJECT, MODES

  9. If SCOPEHASH[interop:AllRemoteFromAgent] is not empty

    1. For each Remote Agent Data Registration RADR in SCOPEHASH[interop:AllRemoteFromAgent]

      1. Call § 8.4.19 Apply Resource Permissions with inputs: SCOPEHASH[interop:AllRemoteFromAgent][RADR], SUBJECT, MODES

  10. If SCOPEHASH[interop:SelectedRemote] is not empty

    1. For each Data Grant or Referenced Data Grant DATAGRANT in SCOPEHASH[interop:SelectedRemote]

      1. 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
  1. Let SUBJECT be the Access Grant Subject GRANT hasAccessGrantSubject

  2. For each Trusted Grant TGRANT linked via GRANT hasTrustedGrant

    1. Let MODES be the access modes linked via TGRANT accessMode

    2. If TGRANT trustedWithType is interop:Agent

      1. Let PROFILE be TGRANT trustedWith

      2. Call § 8.4.19 Apply Resource Permissions with inputs: PROFILE, SUBJECT, MODES

    3. If TGRANT trustedWithType is interop:RegistrySet

      1. Let SET be TGRANT trustedWith

      2. Let REGISTRIES be the Registries linked via SET hasRegistry

      3. Call § 8.4.19 Apply Resource Permissions with inputs: SET, SUBJECT, MODES

      4. For each Registry REGISTRY in REGISTRIES

        1. Call § 8.4.19 Apply Resource Permissions with inputs: REGISTRY, SUBJECT, MODES

    4. If TGRANT trustedWithType is interop:Registry

      1. Let REGISTRY be TGRANT trustedWith

      2. 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
  1. Call § 8.4.21 Remove Resource Permissions with inputs: RESOURCE, SUBJECT

  2. Add a new Authorization Statement NEWSTATEMENT to ACL

  3. Set NEWSTATEMENT Access Grant Subject to SUBJECT.

  4. Set the access modes for NEWSTATEMENT to MODES

  5. If RESOURCE is a container

    1. 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

  1. Call § 8.4.21 Remove Resource Permissions with inputs: RESOURCE, SUBJECT

  2. Add a new Authorization Statement NEWSTATEMENT to ACL

  3. Set NEWSTATEMENT Access Grant Subject to SUBJECT

  4. Set a condition on NEWSTATEMENT that access is only permitted when a graph link is present composed of subject: CONDSUB, predicate: CONDPRED, object: CONDOBJ

  5. Set the access modes for NEWSTATEMENT to MODES

  6. If RESOURCE is a container

    1. 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
  1. Let ACL be the ACL Resource directly associated with RESOURCE

  2. Let STATEMENTS be any Authorization Statements in ACL directly associated with SUBJECT.

  3. For each STATEMENT in STATEMENTS

    1. Remove Access Grant Subject from STATEMENT

    2. 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
  1. For each Access Need NEED in GROUP

    1. Call § 8.4.23 Deny Data Grant with inputs: NEED hasDataGrant, GRANT

    2. Call § 8.4.36 Deny Remote Data Grant with inputs: NEED hasRemoteDataGrant, GRANT

  2. For each Trusted Need TNEED in GROUP

    1. 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
  1. Let DG scopeOfGrant be interop:NoAccess

  2. For each Referenced Data Grant REFDG linked via DG hasReferencedDataGrant

    1. 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
  1. Let REFDG scopeOfGrant be interop: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
  1. Let DG scopeOfGrant be interop:AllInstances

  2. Remove all links for DG hasDataInstance

  3. For each Referenced Data Grant REFDG linked via DG hasReferencedDataGrant

    1. 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
  1. Let REFDG scopeOfGrant be interop:AllInstances

  2. 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
  1. Let DG scopeOfGrant be interop:SelectedInstances

  2. Let DG hasDataInstance be linked to one unique instance of DI

  3. For each Referenced Data Grant REFDG linked via DG hasReferencedDataGrant

    1. 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
  1. Let REFDG scopeOfGrant be interop:InheritInstances

  2. 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
  1. Let REFDG scopeOfGrant be interop:SelectedInstances

  2. Let REFDG hasDataInstance be linked to one unique instance of DI

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
  1. Let RDG scopeOfGrant be interop:AllRemote

  2. Remove all links for RDG hasRemoteDataFromAgent

  3. Remove all links for RDG hasDataGrant

  4. Remove all links for RDG hasReferencedDataGrant

  5. For each Referenced Remote Data Grant REFRDG linked via RDG hasReferencedRemoteDataGrant

    1. 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
  1. Let REFRDG scopeOfGrant be interop:AllRemote

  2. Remove all links for REFDG hasRemoteDataFromAgent

  3. Remove all links for REFDG hasDataGrant

  4. 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
  1. Let RDG scopeOfGrant be interop:AllRemoteFromAgent

  2. Remove all links for RDG hasDataGrant

  3. Remove all links for RDG hasReferencedDataGrant

  4. Let RDG hasRemoteDataFromAgent be linked to one unique instance of RADR

  5. For each Referenced Remote Data Grant REFRDG linked via RDG hasReferencedRemoteDataGrant

    1. 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
  1. Let REFRDG scopeOfGrant be interop:AllRemoteFromAgent

  2. Remove all links for REFRDG hasDataGrant

  3. Remove all links for REFRDG hasReferencedDataGrant

  4. Let REFRDG hasRemoteDataFromAgent be linked to one unique instance of RADR

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
  1. Let RDG scopeOfGrant be interop:SelectedRemote

  2. Remove all links for RDG hasRemoteDataFromAgent

  3. If DATAGRANT is a Data Grant

  4. Let RDG hasDataGrant be linked to DATAGRANT

  5. If DATAGRANT is a Referenced Data Grant

  6. Let RDG hasReferencedDataGrant be linked to DATAGRANT

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
  1. Let REFRDG scopeOfGrant be interop:SelectedRemote

  2. Remove all links for REFRDG hasRemoteDataFromAgent

  3. If DATAGRANT is a Data Grant

  4. Let REFRDG hasDataGrant be linked to DATAGRANT

  5. If DATAGRANT is a Referenced Data Grant

  6. Let REFRDG hasReferencedDataGrant be linked to DATAGRANT

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
  1. Let RDG scopeOfGrant be interop:NoAccess

  2. For each Referenced Remote Data Grant REFRDG linked via RDG hasReferencedRemoteDataGrant

    1. 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
  1. Let REFRDG scopeOfGrant be interop: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
  1. Let TG scopeOfGrant be interop:TrustedAccess

  2. Let TG trustedWith be SET

  3. Let TG trustedWithType be SET 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
  1. Let TG scopeOfGrant be interop:TrustedAccess

  2. Let TG trustedWith be REG

  3. Let TG trustedWithType be SET 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
  1. Let TG scopeOfGrant be interop: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.

An Access Receipt Registry Set at https://bob.pod.example/profile/receipt#set linking to two different Access Receipt Registries
<#set>
  a interop:AccessReceiptRegistrySet;
  interop:hasRegistry 
    <https://bob.pod.example/receipts/#registry> ,
    <https://bob.otherpod.example/receipts/#registry> .
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.

An Access Receipt Registry at https://bob.pod.example/receipts/#registry linking to several registered Access Receipts
<#registry>
  a interop:AccessReceiptRegistry ;
  interop:hasRegistration 
    <fa6d6553-0308-4abd-bce6-888df653695a#receipt> ,
    <d49eae8c-e138-4153-86ed-63832deadc6b#receipt> ,
    <506a0cee-1dc9-4720-a768-294aa0284502#receipt> .
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.

An Access Receipt at https://bob.pod.example/receipts/fa6d6553-0308-4abd-bce6-888df653695a#receipt
<#receipt>
  a interop:AccessReceipt ;
  interop:registeredBy https://bob.pod.example/profile/id#me ;
  interop:registeredWith https://trusted.example/id#agent ;
  interop:registeredAt "2020-09-05T06:15:01Z"^^xsd:dateTime ;
  interop:updatedAt "2020-09-05T06:15:01Z"^^xsd:dateTime ;
  interop:providedAt "2020-09-05T06:15:01Z"^^xsd:dateTime ;
  interop:fromAgent https://alice.pod.example/profile/id#me ;
  interop:viaAgent https://alice.pod.example/profile/id#me ;
  interop:hasAccessGrantSubject <#grant-subject> ;
  interop:hasAccessNeedGroup <#need-group-pm> ;
  interop:hasDataGrant <#data-grant-project> .
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
  1. Let SUBJECT be the Access Grant Subject linked via GRANT hasAccessGrantSubject

  2. Let AGENT be SUBJECT accessByAgent

  3. Let APP be SUBJECT accessByApplication

  4. If APP is not empty

    1. If APP receivesAccessReceipt is interop:ReceiptInRegistration

      1. Let RECEIPT be result of § 9.4.2 Provide Receipt in Application Registration with inputs: GRANT

    2. If APP receivesAccessReceipt is interop:ReceiptInMessage

      1. Let RECEIPT be result of § 9.4.3 Provide Receipt in Message with inputs: GRANT

  5. If APP is empty and AGENT is not empty

    1. Return error if AGENT receivesAccessReceipt is not interop:ReceiptInMessage

    2. Let RECEIPT be result of § 9.4.3 Provide Receipt in Message with inputs: GRANT

  6. 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
  1. Let RECEIPT be an empty Access Receipt

  2. Let SUBJECT be the Access Grant Subject linked via GRANT hasAccessGrantSubject

  3. Let GRANTOR be the current Agent

  4. Let OWNER be the Agent owner of the storage access is being granted from

  5. Let APP be SUBJECT accessByApplication

  6. Let RECEIPT fromAgent be OWNER

  7. Let RECEIPT viaAgent be GRANTOR

  8. Let RECEIPT providedAt be the current time

  9. Let RECEIPT hasAccessGrantSubject be SUBJECT

  10. Let RECEIPT hasAccessNeedGroup be all Access Need Groups linked via GRANT hasAccessNeedGroup

  11. Let RECEIPT hasDataGrant be all Data Grants linked via GRANT hasDataGrant

  12. Let RECEIPT hasTrustedGrant be all Trusted Grants linked via GRANT hasTrustedGrant

  13. Let RECEIPT hasRemoteDataGrant be all Remote Data Grants linked via GRANT hasRemoteDataGrant

  14. Let APPREG be result of § 4.5.1 Load Application Registration with inputs: OWNER, APP

    1. Call § 4.5.2 Register Application if APPREG is empty

  15. Post RECEIPT to APPREG container

  16. Let CURRENT be APPREG hasAccessReceipt

  17. Remove CURRENT if it exists

  18. Let APPREG hasAccessReceipt be CURRENT

  19. 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
  1. Let RECEIPT be an empty Access Receipt

  2. Let SUBJECT be the Access Grant Subject linked via GRANT hasAccessGrantSubject

  3. Let GRANTEE be SUBJECT accessByAgent

  4. Let GRANTOR be the current Agent

  5. Let OWNER be the Agent owner of the storage access is being granted from

  6. Let RECEIPT fromAgent be OWNER

  7. Let RECEIPT viaAgent be GRANTOR

  8. Let RECEIPT providedAt be the current time

  9. Let RECEIPT hasAccessGrantSubject be SUBJECT

  10. Let RECEIPT hasAccessNeedGroup be all Access Need Groups linked via GRANT hasAccessNeedGroup

  11. Let RECEIPT hasDataGrant be all Data Grants linked via GRANT hasDataGrant

  12. Let RECEIPT hasTrustedGrant be all Trusted Grants linked via GRANT hasTrustedGrant

  13. Let RECEIPT hasRemoteDataGrant be all Remote Data Grants linked via GRANT hasRemoteDataGrant

  14. Post RECEIPT to GRANTEE hasAccessInbox

  15. 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
  1. Let CURRENT be an Access Receipt returned by § 9.4.5 Load Access Receipt with inputs: RECEIPT fromAgent, REGISTRY

  2. If CURRENT is empty

    1. Add RECEIPT to REGISTRY

    2. Link RECEIPT to REGISTRY via REGISTRY hasRegistration

  3. If CURRENT is not empty

    1. Update CURRENT with RECEIPT

  4. Call § 10.4.3 Update Remote Data with inputs: RECEIPT

  5. Return RECEIPT

9.4.5. Load Access Receipt

Description

This operation looks up an Access Receipt in an Access Receipt Registry REGISTRY based on the Agent owner of the data that was shared.

Inputs
AGENT Agent owner of the shared data
REGISTRY Access Receipt Registry to lookup
Outputs
Access Receipt Corresponding to AGENT in REGISTRY
  1. For each Access Receipt RECEIPT included in REGISTRY hasRegistration

    1. return RECEIPT if RECEIPT 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.

A Remote Data Registry Set at https://bob.pod.example/profile/remote#set linking to two different Remote Data Registries
<#set>
  a interop:RemoteDataRegistrySet;
  interop:hasRegistry 
    <https://alice.pod.example/remote/#registry> ,
    <https://alice.otherpod.example/remote/#registry> .
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.

An Remote Data Registry at https://alice.pod.example/remote/#registry linking to several Remote Data Registrations
<#registry>
  a interop:RemoteDataRegistry ;
  interop:hasRemoteDataRegistration
    <9e80126d-178f-4a03-851b-c731194a3b0d/#registration> ,
    <833ab294-9f29-4059-b76f-00efc251f2dd/#registration> ,
    <656a8fd0-7cac-46a3-8b84-06f227822656/#registration> .      
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.

A Remote Data Registration for a given shape tree at https://alice.pod.example/remote/9e80126d-178f-4a03-851b-c731194a3b0d/#set linking to several Remote Agent Data Registrations
<#registration>
  a interop:RemoteDataRegistration ;
  interop:registeredBy <https://alice.pod.example/profile/id#me> ;
  interop:registeredWith <https://trusted.example/id#agent> ;
  interop:registeredAt "2020-09-05T06:15:01Z"^^xsd:dateTime ;
  interop:updatedAt "2020-09-05T06:15:01Z"^^xsd:dateTime ;
  interop:registeredShapeTree project:ProjectTree ;
  interop:hasRemoteAgentDataRegistration
    <f0ebbd29-3a5a-4770-af29-cdb7693066b4/#registration> ,
    <bedcc388-f303-4059-8645-2e93bf61e9f3/#registration> .
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 IRI 
  interop: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 at https://alice.pod.example/remote/9e80126d-178f-4a03-851b-c731194a3b0d/f0ebbd29-3a5a-4770-af29-cdb7693066b4/#registration
<#registration>
  a interop:RemoteAgentDataRegistration ;
  interop:registeredBy <https://alice.pod.example/profile/id#me> ;
  interop:registeredWith <https://trusted.example/id#agent> ;
  interop:registeredAt "2020-09-05T06:15:01Z"^^xsd:dateTime ;
  interop:updatedAt "2020-09-05T06:15:01Z"^^xsd:dateTime ;
  interop:registeredShapeTree project:ProjectTree ;
  interop:hasDataRegistration 
    <https://bob.pod.example/data/project-tree/#registration> ;    
  interop:fromAgent
    <https://bob.pod.example/profile/id#me> ;
  interop:hasAccessReceipt
    <https://bob.pod.example/receipts/fa6d6553-0308-4abd-bce6-888df653695a#receipt> ;
  interop:satisfiesDataGrant
    <cd04e76b-d64d-4cea-aacf-fb248a295002#instance> .
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

Resource Class Shape Shape Tree
/profile/ - - ProfileTree
-- remote#set RemoteDataRegistrySet RemoteDataRegistrySetShape RemoteDataRegistrySetTree
/remote/#registry RemoteDataRegistry RemoteDataRegistryShape RemoteDataRegistryTree
-- 9e80126d...0d/#reg... RemoteDataRegistration RemoteDataRegistrationShape RemoteDataRegistrationTree
---- f0ebbd29...b4/#reg... RemoteAgentDataRegistration RemoteAgentDataReg... RemoteAgentDataReg...
------ cd04e76b...02#dg DataGrant DataGrantShape DataGrantTree
------ 9506b58f...eb#rdg ReferencedDataGrant ReferencedDataGrantShape ReferencedDataGrantTree
---- bedcc388...f3/#reg... RemoteAgentDataRegistration RemoteAgentDataReg... RemoteAgentDataReg...
------ fe111165a...01#dg DataGrant DataGrantShape DataGrantTree
-- 833ab294...dd/#reg... RemoteDataRegistration RemoteDataRegistrationShape RemoteDataRegistrationTree
---- 265dff0c...12/#reg... RemoteAgentDataRegistration RemoteAgentDataReg... RemoteAgentDataReg...
------ 62262350...4a#rdg ReferencedDataGrant ReferencedDataGrantShape ReferencedDataGrantTree
-- 656a8fd0...56/#reg... RemoteDataRegistration RemoteDataReg... RemoteDataReg...
---- f68e95eb...15/#reg... RemoteAgentDataRegistration RemoteAgentDataReg... RemoteAgentDataReg...
------ a2752e58...b6#dg DataGrant DataGrantShape DataGrantTree
------ d1133f58...60#dg DataGrant DataGrantShape DataGrantTree

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

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
  1. For each Remote Data Registration RDR in REGISTRY linked via REGISTRY hasRemoteDataRegistration

    1. return RDR if RDR 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
  1. Let EXISTING be a Remote Data Registration returned by § 10.4.1 Load Remote Data Registration with inputs: TREE,REGISTRY

    1. Error if EXISTING

  2. Let RDR be an empty Remote Data Registration

  3. Let RDR registeredBy be the current Agent

  4. Let RDR registeredWith be the current Application

  5. Let RDR registeredAt be the current timestamp

  6. Let RDR updatedAt be the current timestamp

  7. Let RDR registeredShapeTree be TREE

  8. PUT RDR into REGISTRY container

  9. Link RDR to REGISTRY via REGISTRY hasRemoteDataRegistration

  10. Return RDR

10.4.3. Update Remote Data

Description

This operation updates a Remote Data Registry REGISTRY based on an input Access Receipt RECEIPT.

It iterates over each Data Grant linked via RECEIPT hasDataGrant, including following any Referenced Data Grants.

All Data Grants and Referenced Data Grants are added to a hash map DRHASH. The key is the shared Data Registration associated with each Data Grant or Referenced Data Grant via hasDataRegistration.

The end result is the keys of DRHASH are a unique set of Data Registrations associated with RECEIPT, and each key has an array of related Data Grants and Referenced Data Grants as its value.

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
  1. 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.

  2. For each Data Grant DG linked via RECEIPT hasDataGrant

    1. Let DRKEY be DG hasDataRegistration added or found in DRHASH

    2. Add DG to the value array for DRKEY if missing

    3. For each Referenced Data Grant REFDG linked via DG hasReferencedDataGrant

      1. Let REFDRKEY be REFDG hasDataRegistration added or found in DRHASH

      2. Add REFDG to the array for REFDRKEY if missing

  3. For each Data Registration DR in DRHASH

    1. Call § 10.4.6 Update Remote Agent Data Registration with inputs: DR, DRHASH[DR], RECEIPT

  4. 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
  1. For each Remote Data Registration RDR in REGISTRY linked via REGISTRY hasRemoteDataRegistration

    1. If RDR registeredShapeTree == DATAREG registeredShapeTree

    2. For each Remote Agent Data Registration RADR linked via RDR hasRemoteAgentDataRegistration

      1. return RADR if RADR 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
  1. Let RDR be a Remote Data Registration returned by § 10.4.1 Load Remote Data Registration with inputs: DR registeredShapeTree, REGISTRY

    1. If RDR is missing, let RDR be a Remote Data Registration returned by § 10.4.2 Create Remote Data Registration with inputs: DR registeredShapeTree, REGISTRY

  2. Let RADR be an empty Remote Agent Data Registration

  3. Let RADR registeredBy be the current Agent

  4. Let RADR registeredWith be the current Application

  5. Let RADR registeredAt be the current timestamp

  6. Let RADR updatedAt be the current timestamp

  7. Let RADR hasDataRegistration be DR

  8. Let RADR registeredShapeTree be DR registeredShapeTree

  9. Let RADR fromAgent be RECEIPT fromAgent

  10. Let RADR hasAccessReceipt be RECEIPT

  11. PUT RADR into the RDR container

  12. Link RADR to RDR via RDR hasRemoteAgentDataRegistration

  13. 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
  1. Let RADR be a Remote Agent Data Registration returned from calling § 10.4.4 Load Remote Agent Data Registration with inputs: DR, REGISTRY

  2. If RADR is missing

    1. Call § 10.4.5 Create Remote Agent Data Registration with inputs: RECEIPT, REGISTRY

  3. For each DATAGRANT in DATAGRANTS

    1. PUT DATAGRANT into RADR container if it does not already exist

    2. PATCH DATAGRANT in RADR container if it already exists

  4. 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

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[SERVICE-WORKERS-1]
Alex Russell; et al. Service Workers 1. 19 November 2019. CR. URL: https://www.w3.org/TR/service-workers-1/
[WAC]
Web Access Control. URL: https://solid.github.io/specification/wac/

Informative References

[DID]
Drummond Reed; et al. Decentralized Identifiers (DIDs) v1.0. URL: https://www.w3.org/TR/did-core/
[PROBLEMS-AND-GOALS]
Justin Bingham; et al. Problems and Goals for Interoperability, Collaboration, and Security in a Solid Pod. URL: https://github.com/solid/data-interoperability-panel/blob/master/problems-and-goals.md
[SHACL]
Holger Knublauch; Dimitris Kontokostas. Shapes Constraint Language (SHACL). URL: https://www.w3.org/TR/shacl/
[SHAPETREES]
Justin Bingham; et al. Shape Trees. URL: https://shapetrees.org/TR/specification/index.html
[SHEX]
Eric Prud'hommeaux; et al. Shape Expressions Language 2.1. URL: http://shex.io/shex-semantics/index.html
[WEBID]
Tim Berners-Lee; Henry Story; Andrei Sambra. WebID 1.0. URL: https://www.w3.org/2005/Incubator/webid/spec/identity/
[WEBID-OIDC]
Dmitri Zagidulin. WebID-OIDC Authentication Specification. URL: https://github.com/solid/webid-oidc-spec

Issues Index

Detail how an application service is looked up in the Application Profile.
Detail how an Agent can be redirected to an application service
detail how an Agent is returned back from an application service
Is it necessary to use a one-way hash for application registration resource names. Github issue
Define app registration service
Cleanup of related data may need to be specified
Cleanup of related data may need to be specified
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.
Define data authorization service
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.
Write standard operation for invitation delivery
Write standard operation for validating an invitation
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