Update data agreement
PUT/config/data-agreement/:dataAgreementId
This endpoint allows the admin to update the latest data agreement defined earlier in an organisation. It also returns the updated revision number.
Request
Path Parameters
Unique ID of an object
- application/json
Body
- Array [
- Array [
- ]
- ]
- Array [
- ]
dataAgreement object
An agreement contains the specification of a single purpose that can be consented to. An DataAgreement is universal and can be consented to by many individuals through a DataAgreementRecord"
The version of this specification to which a receipt conforms
ID of the controller
URL of data controller (may be omitted if no data involved)
Name of data controller (may be omitted if no data involved)
policy objectrequired
Policy under which this DataAgreement shall be governed. When creating a data agreement, the latest policy can be used to fill the default value, and organisation admin can decide to change it in data agreement level
Name of the policy
Version of the policy. It can follow semver format.
Permanent URL at which this very version of the Policy can be read, should not be allowed to change over time.
Jurisdiction
Industry sector
Data retention period in days
Geographic restriction
Storage location
Third party data sharing
dataAttributes object[]
"Data attribute contains specifications of exactly what is collected."
Data attribute Id
Name of the attribute, for instance "name" or "age"
Description of the attribute
Sensitivity of data attribute
Category for data attribute
restrictions object[]
Credential definition id
Schema id
Name of purpose
Description of purpose
Possible values: [consent, legal_obligation, contract, vital_interest, public_task, legitimate_interest]
Lawful basis of the agreement - consent / legal_obligation / contract / vital_interest / public_task / legitimate_interest
Possible values: [null, data_source, data_using_service]
null/data_source/data_using_service
The date on which the DPIA report is generated after a DPIA
The URl providing the DPIA result reports, summary etc that can be verified by any interested parties
signature object
Signature of authorizing party of DataAgreement. Note: Signatures may be chained in case of multiple signatures.
Objects may be passed back by some API endpoints without an id (PK), denoting that they are a "draft", i.e. a Signature that is not yet stored in the database and only exist in transit.
The final payload that is signed, constructed as a JSON serialization of fields {verificationPayload: ..., verificationPayloadHash: ..., verificationMethod: ..., verificationArtifact: ..., verificationSignedBy: ..., verificationJwsHeader, timestamp: ..., signedWithoutObjectReference: ..., objectType: ..., objectReference: ...}. Serialized as a JSON dict. If the signature is generated before anything is stored in the database (and has a PK), then the objectReference should be omitted from the payload but filled in afterwards.
Signature of payload hash, the format of the signature should be specified by either verificationMethod or verificationJwsHeader
A well-known string denoting which method is used. Valid values:
Internally generated serialized version of the data referenced by objectType and objectReference - by extracting and serializing their data as JSON.
Internally generated cryptographic hash of the value to be signed, i.e. the value of verificationPayload
A verification artifact in the form of a scanned object, image, signature etc.
Because an identifier's information may change over time, there is a need to store that information at the time of signing. In case of a cryptographic signature, this field should contain some identifier for looking up or verifying the public key of the signing party. In case of a non-cryptographic signature, this field could contain a natural individual's names, personal number, email addresses - store a snapshot that binds to the signature at the time of signing. In case of a cryptographic signature, this may be the fingerprint of the individual's public key or in some cases, a token from the user's ID session.
DRAFT FIELD: Specifies the relationship between the authorizing signature and the invidual which the payload concerns. This is relevant for Consent Records. Possible values: "individual" / "delegate"
Alternative to the verificationMethod, verificationHash and verificationSignature, give a JWS serialized object (RFC7515)
Timestamp of signature, currently this field isn't part of the payload so it's not tamper-proof.
Indicates that objectReference was left blank in the serialized version that was signed.
Possible values: [revision, signature]
Name of the schema model that objectReference points to. Values: "signature" or "revision"
A symmetric relation / back reference to the objectType that was signed. We are currently just modelling signing another signature (a chain) or signing a Revision (which can be a revision of a consent record, an agreement, policy etc)
DataAgreement is active and new DataAgreementRecords can be created.
DataAgreementRecord may be deleted when consent is withdrawn, as its existence is not necessary for auditability.
WIP: This field indicates that Data Agreement Records may be transferred from this compatible previous revision of the same DataAgreement.
Possible values: [draft, complete]
WIP: Current Lifecycle state of the DataAgreement. Lifecycle states are used to manage internal workflows and should not be assigned semantic meanings for active Data Agreement Records.
dataExchange objectrequired
data exchange details
Possible values: [AIP10]
Data exchange profile
Data agreement id defined in AIP
Credential definition identifier
Schema identifier
Is schema existing
presentationRequest object
Name of the presentation request
Version of the presentation request
requestedAttributes object
Map of requested attributes
Name of the requested attribute
restrictions object[]
List of restrictions for the requested attribute
Schema identifier
Credential definition identifier
Responses
- 200
- 400
Response Headers
- application/json
- Schema
- Example (from schema)
Schema
- Array [
- Array [
- ]
- ]
- Array [
- ]
dataAgreement object
An agreement contains the specification of a single purpose that can be consented to. An DataAgreement is universal and can be consented to by many individuals through a DataAgreementRecord"
The version of this specification to which a receipt conforms
ID of the controller
URL of data controller (may be omitted if no data involved)
Name of data controller (may be omitted if no data involved)
policy objectrequired
Policy under which this DataAgreement shall be governed. When creating a data agreement, the latest policy can be used to fill the default value, and organisation admin can decide to change it in data agreement level
Name of the policy
Version of the policy. It can follow semver format.
Permanent URL at which this very version of the Policy can be read, should not be allowed to change over time.
Jurisdiction
Industry sector
Data retention period in days
Geographic restriction
Storage location
Third party data sharing
dataAttributes object[]
"Data attribute contains specifications of exactly what is collected."
Data attribute Id
Name of the attribute, for instance "name" or "age"
Description of the attribute
Sensitivity of data attribute
Category for data attribute
restrictions object[]
Credential definition id
Schema id
Name of purpose
Description of purpose
Possible values: [consent, legal_obligation, contract, vital_interest, public_task, legitimate_interest]
Lawful basis of the agreement - consent / legal_obligation / contract / vital_interest / public_task / legitimate_interest
Possible values: [null, data_source, data_using_service]
null/data_source/data_using_service
The date on which the DPIA report is generated after a DPIA
The URl providing the DPIA result reports, summary etc that can be verified by any interested parties
signature object
Signature of authorizing party of DataAgreement. Note: Signatures may be chained in case of multiple signatures.
Objects may be passed back by some API endpoints without an id (PK), denoting that they are a "draft", i.e. a Signature that is not yet stored in the database and only exist in transit.
The final payload that is signed, constructed as a JSON serialization of fields {verificationPayload: ..., verificationPayloadHash: ..., verificationMethod: ..., verificationArtifact: ..., verificationSignedBy: ..., verificationJwsHeader, timestamp: ..., signedWithoutObjectReference: ..., objectType: ..., objectReference: ...}. Serialized as a JSON dict. If the signature is generated before anything is stored in the database (and has a PK), then the objectReference should be omitted from the payload but filled in afterwards.
Signature of payload hash, the format of the signature should be specified by either verificationMethod or verificationJwsHeader
A well-known string denoting which method is used. Valid values:
Internally generated serialized version of the data referenced by objectType and objectReference - by extracting and serializing their data as JSON.
Internally generated cryptographic hash of the value to be signed, i.e. the value of verificationPayload
A verification artifact in the form of a scanned object, image, signature etc.
Because an identifier's information may change over time, there is a need to store that information at the time of signing. In case of a cryptographic signature, this field should contain some identifier for looking up or verifying the public key of the signing party. In case of a non-cryptographic signature, this field could contain a natural individual's names, personal number, email addresses - store a snapshot that binds to the signature at the time of signing. In case of a cryptographic signature, this may be the fingerprint of the individual's public key or in some cases, a token from the user's ID session.
DRAFT FIELD: Specifies the relationship between the authorizing signature and the invidual which the payload concerns. This is relevant for Consent Records. Possible values: "individual" / "delegate"
Alternative to the verificationMethod, verificationHash and verificationSignature, give a JWS serialized object (RFC7515)
Timestamp of signature, currently this field isn't part of the payload so it's not tamper-proof.
Indicates that objectReference was left blank in the serialized version that was signed.
Possible values: [revision, signature]
Name of the schema model that objectReference points to. Values: "signature" or "revision"
A symmetric relation / back reference to the objectType that was signed. We are currently just modelling signing another signature (a chain) or signing a Revision (which can be a revision of a consent record, an agreement, policy etc)
DataAgreement is active and new DataAgreementRecords can be created.
DataAgreementRecord may be deleted when consent is withdrawn, as its existence is not necessary for auditability.
WIP: This field indicates that Data Agreement Records may be transferred from this compatible previous revision of the same DataAgreement.
Possible values: [draft, complete]
WIP: Current Lifecycle state of the DataAgreement. Lifecycle states are used to manage internal workflows and should not be assigned semantic meanings for active Data Agreement Records.
dataExchange objectrequired
data exchange details
Possible values: [AIP10]
Data exchange profile
Data agreement id defined in AIP
Credential definition identifier
Schema identifier
Is schema existing
presentationRequest object
Name of the presentation request
Version of the presentation request
requestedAttributes object
Map of requested attributes
Name of the requested attribute
restrictions object[]
List of restrictions for the requested attribute
Schema identifier
Credential definition identifier
revision object
A generic revision model captures the serialized contents of any schema's single row. This is then subject to 1) cryptographic signature and 2) auditing.
Aside from "successor" column, a revision should be considered locked.
Revision Id
Possible values: [dataAgreement, policy, dataAgreementRecord]
This was previously called "schema" but for technical reasons should be called "schemaName"
The PK of the object that was serialized.
The object that is serialised.
Indicates that objectId was left blank in serizalizedSnapshot when calculating serializedHash. objectId may be subsequently filled in.
Revisioned data (serialized as JSON) as a dict. Apply JSON Canonicalization Scheme as per IETF RFC 8785. It contains all the fields of the schema except sucessorId, serializedHash, serializedSnapshot.
Hash of serizalizedSnapshot (SHA-1)
Timestamp of when revisioning happened. It should be ISO 8601 UTC date time
Individual Id
Reference to an admin user that has created this revision
If this revision is no longer the latest revision, refer to its successor.
Tamper-resistent artifact from previous record, copied from serializedHash
Tamper-resistent artifact from previous record (we don't know if the previous record was signed or not)
{
"dataAgreement": {
"id": "",
"version": "",
"controllerId": "string",
"controllerUrl": "string",
"controllerName": "string",
"policy": {
"id": "",
"name": "",
"version": "",
"url": "",
"jurisdiction": "",
"industrySector": "",
"dataRetentionPeriodDays": "",
"geographicRestriction": "",
"storageLocation": "",
"thirdPartyDataSharing": true
},
"dataAttributes": [
{
"id": "",
"name": "",
"description": "",
"sensitivity": "",
"category": "",
"restrictions": [
{
"credDefId": "H3DW1MUWZyBkP5LG4rTYRH:3:CL:80:default",
"schemaId": "H3DW1MUWZyBkP5LG4rTYRH:2:Certificate Of Registration:6.0.0"
}
]
}
],
"purpose": "string",
"purposeDescription": "string",
"lawfulBasis": "",
"methodOfUse": "",
"dpiaDate": "",
"dpiaSummaryUrl": "string",
"signature": {
"id": "",
"payload": "",
"signature": "",
"verificationMethod": "",
"verificationPayload": "",
"verificationPayloadHash": "",
"verificationArtifact": "",
"verificationSignedBy": "",
"verificationSignedAs": "",
"verificationJwsHeader": "",
"timestamp": "",
"signedWithoutObjectReference": "",
"objectType": "",
"objectReference": ""
},
"active": "",
"forgettable": "",
"compatibleWithVersionId": "string",
"lifecycle": "draft",
"dataUsingServices": [
null
],
"dataExchange": {
"dataExchangeProfile": "AIP10",
"id": "string",
"credentialDefinitionId": "string",
"schemaId": "string",
"isExistingSchema": true,
"qrId": "string",
"firebaseDynamicLink": "string",
"presentationRequest": {
"name": "string",
"version": "string",
"requestedAttributes": {
"name": "string",
"restrictions": [
{
"schemaId": "string",
"credDefId": "string"
}
]
}
}
}
},
"revision": {
"id": "",
"schemaName": "",
"objectId": "",
"objectData": "",
"signedWithoutObjectId": "",
"serizalizedSnapshot": "",
"serializedHash": "",
"timestamp": "",
"authorizedByIndividualId": "string",
"authorizedByOtherId": "",
"successorId": "string",
"predecessorHash": "",
"predecessorSignature": ""
}
}
bad input parameter