Upd: audit endpoints

Signed-off-by: George J Padayatti <[email protected]>

openapi/v2023.8.2/definitions/DPIA.yaml

@@ -0,0 +1,14 @@
+title: Data agreement
+type: object
+description: DPIA details
+required:
+  - dpia_timestamp
+  - dpia_summary_url
+properties:
+  dpia_timestamp:
+    type: string
+    description: UTC timestamp in epoch seconds when the DPIA was performed
+
+  dpia_summary_url:
+    type: string
+    description: URL to the DPIA summary

openapi/v2023.8.2/definitions/DataAgreement.yaml

@@ -1,82 +1,70 @@
 title: Data agreement
 type: object
-description: >
-  The Data Agreement Vocabulary provides terms to describe and represent information related to 
-  processing of personal data based on established requirements such as for the EU General Data 
-  Protection Regulation (GDPR).
+description: |
+  A data agreement contains the specification of a single purpose that can be consented to. 
+  A data greement is universal and can be consented to by *many* individuals through a data agreement record.
+required:
+  - id
+  - version
+  - lawful_basis
+  - dpia
 properties:
-  language:
+  id:
     type: string
-    description: Language code for e.g. en-gb
+    description: "Data agreement identifier"
+
   version:
     type: string
-    description: Version number of the data agreement
-  dataControllerName:
-    type: string
-    description: An organisation constituted as a legally defined entity in any jurisdiction.
-  dataControllerUrl:
-    type: string
-    description: Organisation or data controller URL.
-  dataPolicy:
-    description: Encapsulate the data policies used in the use of personal data.
-    $ref: "./GlobalDataPolicyConfiguration.yaml"
+    description: "The version of this specification to which a data agreement conforms"
+
+  data_controller:
+    $ref: "./DataController.yaml"
+    description: "Data source organisation details"
+
+  data_policy:
+    $ref: "./DataPolicy.yaml"
+    description: "Global policy configuration"
+
   purpose:
-    description: >
-      Describes the purpose for which a data controller (Data Source or Data Using Service) uses personal data for. 
-      This is also the purpose for which the data agreeent is being formulated
-    type: string
-  purposeDescription:
-    description: >
-      Provides description of the purpose for which the personal data us used, 
-      comprehensive to the individual whose data is being used by the data controller.
-    type: string
-  lawfulBasis:
-    description: >
-      An organization processing personal data to have a valid lawful basis for that personal data processing activity. GDPR, 
-      for e.g., consent, legal_obligation, contract, vital_interest, public_task and legitimate_interest.
+    $ref: "./Purpose.yaml"
+    description: "Purpose of an agreement"
+
+  lawful_basis:
     type: string
-  methodOfUse:
-    description: >
-      This is used to describe whether controller is using personal data for internal purposes of for data exchange towards an external third party. 
-      Data exchange could be for exposing data (as a Data Source) or consuming data as a Data Using Service.
+    description: "Lawful basis of the data agreement"
+    enum:
+      - consent
+      - legal_obligation
+      - contract
+      - vital_interest
+      - public_task
+      - legitimate_interest
+
+  method_of_use:
     type: string
-  dataAttributes:
-    description: >
-      Encapsulates the attributes used for the the usage purpose defined. 
-      Its an array of personal data attributes.
-    type: array
-    items:
-      $ref: "./DataAttribute.yaml"
+    description: |
+      Method of use indicates the data exchange mode of data agreement. 
+      When the data controller wishes to expose the data for consumption it should be data-source.
+      When the data controller wishes to consume the data it should be data-using-service
+    num:
+      - null
+      - data-source
+      - data-using-service
+
   dpia:
-    description: Encapsulate the organisation performing the Data Protection Impact Assessment
-    type: object
-    properties:
-      dpiaDate:
-        description: The date on which the DPIA report is generated after a DPIA.
-        type: string
-      dpiaSummaryUrl:
-        description: >
-          The URl providing the DPIA result reports, summary etc that can be verified by any interested parties.
-        type: string
-    required:
-      - dpiaDate
-      - dpiaSummaryUrl
-  isPublished:
-    description: Is the data agreement published towards individuals or not
-    type: boolean
-  proof:
+    description: "Data Protection Impact Assessment"
+    $ref: "./DPIA.yaml"
+
+  lifecycle:
+    $ref: "./Lifecycle.yaml"
+
+  signature:
     $ref: "./Signature.yaml"
-required:
-  - language
-  - version
-  - dataControllerName
-  - dataControllerUrl
-  - dataPolicy
-  - purpose
-  - purposeDescription
-  - lawfulBasis
-  - methodOfUse
-  - dpia
-  - dataSubjectDid
-  - proof
-  - isPublished
+
+  active:
+    type: boolean
+    description: "Agreement is active and new ConsentRecords can be created."
+
+  forgettable:
+    type: boolean
+    description: "Consent Record may be deleted when consent is withdrawn, as its existence is not necessary for auditability."

openapi/v2023.8.2/definitions/DataAgreementRecord.yaml

@@ -1,34 +1,35 @@
 required:
-  - Purpose
-  - Count
-  - Consents
-  - DataRetention
+  - data_agreement
+  - data_agreement_revision
+  - individual
+  - opt_in
 type: object
-description: Data agreement record captures the individual consents for an agreement
+description: |
+  A Consent Record expresses consent (as defined in this building block's specification) to a single Agreement. 
+  There must be a UNIQUE constraint on (agreement_revision, individual)
 properties:
-  Purpose:
+  id:
+    type: string
+    format: uuid
+    example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+    description: |
+      Objects may be passed back by some API endpoints without an id (PK), denoting that they are a \"draft\", 
+      i.e. a ConsentRecord that is not yet stored in the database and only exist in transit. 
+      Draft ConsentRecords do not have a Revision, but if paired up with a Signature, a valid Revision should be generated.
+  data_agreement:
     description: Data agreement
     $ref: "./DataAgreement.yaml"
-  Count:
-    description: Count of data attributes for which consent has to be obtained
-    $ref: "./ConsentCount.yaml"
-  Consents:
-    type: array
-    description: Count of data attributes for which consent has to be obtained
-    items:
-      $ref: "./Consent.yaml"
-  DataRetention:
-    required:
-      - Expiry
-    type: object
-    description: "Data retention settings"
-    properties:
-      Expiry:
-        type: string
-        description: "Data retention expiry in UTC timestamp"
-  DataAgreementRecordRevision:
-    $ref: "./DataAgreementRecordRevision.yaml"
-    description: >
-      A generic revision model captures the serialized contents of any shema's single row. 
-      This is then subject to 1) cryptographic signature and 2) auditing. Aside from successor column, a 
-      revision should be considered locked.
+  data_agreement_revision:
+    description: Data agreement revision
+    $ref: "./Revision.yaml"
+  individual:
+    description: Individual to whom this data agreement record belongs to
+    $ref: "./Individual.yaml"
+  opt_in:
+    type: boolean
+    description: "True: The individual has positively opted in. False: The individual has explicitly said no (or withdrawn a previous consent)."
+  state:
+    type: string
+    description: "The state field is used to record state changes after-the-fact. It is maintained by the Consent BB itself. Valid states: unsigned/pending more signatures/signed"
+  signature:
+    $ref: "./Signature.yaml"

openapi/v2023.8.2/definitions/DataController.yaml

@@ -0,0 +1,20 @@
+type: object
+description: "Details of a data controller."
+required:
+  - id
+  - name
+  - url
+properties:
+  id:
+    type: string
+    format: ""
+    example: ""
+    description: ""
+
+  name:
+    type: string
+    description: "Name of data controller (may be omitted if no data involved)"
+
+  url:
+    type: string
+    description: "URL of data controller (may be omitted if no data involved)"

openapi/v2023.8.2/definitions/DataPolicy.yaml

@@ -0,0 +1,63 @@
+type: object
+description: |
+  A policy governs data and Agreement in the realm of an organisation that is 
+  refered to as "data controller" (GDPR) and owner of referencing Agreements.
+required:
+  - id
+  - name
+  - version
+  - url
+properties:
+  id:
+    type: string
+    format: ""
+    example: ""
+    description: "Policy ID"
+
+  name:
+    type: string
+    format: ""
+    example: ""
+    description: "Name of the policy"
+
+  version:
+    type: string
+    format: ""
+    example: ""
+    description: "Version of the policy"
+
+  url:
+    type: string
+    format: ""
+    example: ""
+    description: "Permanent URL at which this very version of the Policy can be read, should not be allowed to change over time."
+
+  jurisdiction:
+    type: string
+    format: ""
+    example: ""
+    description: "Indicates a legal jurisdiction, e.g. of some legislation, or where some government service is based."
+
+  industry_sector:
+    type: string
+    format: ""
+    example: ""
+    description: "Indicate or restrict scope for interpretation and application of purpose in a domain."
+
+  data_retention_period_days:
+    type: integer
+    format: ""
+    example: ""
+    description: "The amount of time that an organization holds onto any personal data, in days."
+
+  geographic_restriction:
+    type: string
+    format: ""
+    example: ""
+    description: "The geographic restrictions required or followed regarding storage of data."
+
+  storage_location:
+    type: string
+    format: ""
+    example: ""
+    description: "The geographic location where the personal data is stored"

openapi/v2023.8.2/definitions/Individual.yaml

@@ -1,55 +1,47 @@
 required:
-  - ID
-  - Name
-  - IamID
-  - Email
-  - Phone
-  - ImageID
-  - ImageURL
-  - LastVisit
-  - Client
-  - Orgs
+  - id
+  - iamId
+  - orgs
   - APIKey
   - Roles
   - IncompleteProfile
 type: object
+description: |
+  Shallowly models an Individual which may reference some instance in an external system (registration system, functional ID, foundational ID etc). 
+  An Individual instance of this model is not to be mistaken with a unique natural individual. 
+  It is up to the system owner to decide if this record permits mapping to a natural individual and/or if a single Individual row can map to several consent agreements.
 properties:
-  ID:
+  id:
     type: string
-  Name:
+  name:
     type: string
-  IamID:
+    description: "Name of the individual"
+  iamId:
     type: string
-  Email:
+    description: "Consent BB specific IAM ID"
+  external_id:
     type: string
-  Phone:
+    format: ""
+    example: ""
+    description: "Reference to another foundational/functional ID, which is likely PII"
+  external_id_type:
     type: string
-  ImageID:
+    format: ""
+    example: ""
+    description: "External id type specifier. A string. For instance \"email\" or \"foundational id\". Can be used in later queries."
+  lastVisit:
     type: string
-  ImageURL:
-    type: string
-  LastVisit:
-    type: string
-  Client:
-    required:
-      - Token
-      - Type
-    type: object
-    properties:
-      Token:
-        type: string
-      Type:
-        type: integer
-        format: int32
-  Orgs:
+    description: "Last logged-in time"
+  orgs:
     type: array
     items:
       type: string
-  APIKey:
-    type: string
-  Roles:
+      description: "Organisation ID"
+  roles:
     type: array
     items:
       type: string
-  IncompleteProfile:
+      description: "Role ID and organisation ID"
+  incompleteProfile:
     type: boolean
+    description: "Indicates whether the profile is incomplete or not"