openapi: 3.1.0
info:
  title: Nextcloud OpenRegister API
  version: '1.0'
  description: >-
    API for managing registers, schemas, sources, objects, and audit trails in a
    Nextcloud environment.
servers:
  - url: /apps/openregister/api
    description: Base URL for API endpoints
security:
  - basicAuth: []
  - oauth2:
      - read
      - write
tags:
  - name: Registers
    description: Operations related to registers
  - name: Schemas
    description: Operations related to schemas and their properties
  - name: Sources
    description: Operations related to data sources
  - name: Objects
    description: >-
      Operations related to objects, including files, relationships, audit
      trails, and time travel
paths:
  /api/registers:
    get:
      tags:
        - Registers
      summary: Get all registers
      operationId: getRegisters
      responses:
        '200':
          description: List of registers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Register'
    post:
      tags:
        - Registers
      summary: Create a new register
      operationId: createRegister
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Register'
      responses:
        '201':
          description: Register created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Register'
  /api/registers/{uuid}:
    get:
      tags:
        - Registers
      summary: Get a register by UUID
      operationId: getRegister
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Register details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Register'
    put:
      tags:
        - Registers
      summary: Update a register
      operationId: updateRegister
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Register'
      responses:
        '200':
          description: Register updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Register'
    delete:
      tags:
        - Registers
      summary: Delete a register
      operationId: deleteRegister
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Register deleted successfully
  /api/schemas:
    get:
      tags:
        - Schemas
      summary: Get all schemas
      operationId: getSchemas
      responses:
        '200':
          description: List of schemas
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Schema'
    post:
      tags:
        - Schemas
      summary: Create a new schema
      operationId: createSchema
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Schema'
      responses:
        '201':
          description: Schema created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schema'
  /api/schemas/{uuid}:
    get:
      tags:
        - Schemas
      summary: Get a schema by UUID
      operationId: getSchema
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Schema details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schema'
    put:
      tags:
        - Schemas
      summary: Update a schema
      operationId: updateSchema
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Schema'
      responses:
        '200':
          description: Schema updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schema'
    delete:
      tags:
        - Schemas
      summary: Delete a schema
      operationId: deleteSchema
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Schema deleted successfully
  /api/schemas/{uuid}/properties:
    get:
      tags:
        - Schemas
      summary: Get schema properties
      operationId: getSchemaProperties
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Schema properties
          content:
            application/json:
              schema:
                type: object
    post:
      tags:
        - Schemas
      summary: Add schema property
      operationId: addSchemaProperty
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Property added successfully
  /api/schemas/{uuid}/properties/{propertyName}:
    get:
      tags:
        - Schemas
      summary: Get schema property
      operationId: getSchemaProperty
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
        - name: propertyName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Property details
          content:
            application/json:
              schema:
                type: object
    put:
      tags:
        - Schemas
      summary: Update schema property
      operationId: updateSchemaProperty
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
        - name: propertyName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Property updated successfully
    delete:
      tags:
        - Schemas
      summary: Delete schema property
      operationId: deleteSchemaProperty
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
        - name: propertyName
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Property deleted successfully
  /api/schemas/{uuid}/validate:
    post:
      tags:
        - Schemas
      summary: Validate data against schema
      operationId: validateSchema
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Validation results
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                  errors:
                    type: array
                    items:
                      type: string
  /api/sources:
    get:
      tags:
        - Sources
      summary: Get all sources
      operationId: getSources
      responses:
        '200':
          description: List of sources
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Source'
    post:
      tags:
        - Sources
      summary: Create a new source
      operationId: createSource
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Source'
      responses:
        '201':
          description: Source created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Source'
  /api/sources/{uuid}:
    get:
      tags:
        - Sources
      summary: Get a source by UUID
      operationId: getSource
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Source details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Source'
    put:
      tags:
        - Sources
      summary: Update a source
      operationId: updateSource
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Source'
      responses:
        '200':
          description: Source updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Source'
    delete:
      tags:
        - Sources
      summary: Delete a source
      operationId: deleteSource
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Source deleted successfully
  /api/objects:
    get:
      tags:
        - Objects
      summary: Get all objects
      operationId: getObjects
      responses:
        '200':
          description: List of objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ObjectEntity'
    post:
      tags:
        - Objects
      summary: Create a new object
      operationId: createObject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObjectEntity'
      responses:
        '201':
          description: Object created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectEntity'
  /api/objects/{uuid}:
    get:
      tags:
        - Objects
      summary: Get an object by UUID
      operationId: getObject
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Object details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectEntity'
    put:
      tags:
        - Objects
      summary: Update an object
      operationId: updateObject
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObjectEntity'
      responses:
        '200':
          description: Object updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectEntity'
    delete:
      tags:
        - Objects
      summary: Delete an object
      operationId: deleteObject
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Object deleted successfully
  /api/objects/{uuid}/relations:
    get:
      tags:
        - Objects
      summary: Get object relations
      operationId: getObjectRelations
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Object relations
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                    target:
                      type: string
    post:
      tags:
        - Objects
      summary: Add object relation
      operationId: addObjectRelation
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                target:
                  type: string
              required:
                - type
                - target
      responses:
        '201':
          description: Relation added successfully
  /api/objects/{uuid}/files:
    get:
      tags:
        - Objects
      summary: Get object files
      operationId: getObjectFiles
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Object files
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/File'
    post:
      tags:
        - Objects
      summary: Add file to object
      operationId: addObjectFile
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '201':
          description: File added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
  /api/objects/{uuid}/lock:
    post:
      tags:
        - Objects
      summary: Lock an object
      operationId: lockObject
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Object locked successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  lockToken:
                    type: string
  /api/objects/{uuid}/unlock:
    post:
      tags:
        - Objects
      summary: Unlock an object
      operationId: unlockObject
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                lockToken:
                  type: string
              required:
                - lockToken
      responses:
        '200':
          description: Object unlocked successfully
  /api/objects/{uuid}/audit-trails:
    get:
      tags:
        - Objects
      summary: Get object audit trails
      operationId: getObjectAuditTrails
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Object audit trails
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuditTrail'
  /api/objects/{uuid}/versions/{version}:
    get:
      tags:
        - Objects
      summary: Get specific object version
      operationId: getObjectVersion
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
        - name: version
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Object version details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectEntity'
  /api/objects/{uuid}/at/{timestamp}:
    get:
      tags:
        - Objects
      summary: Get object at specific point in time
      operationId: getObjectAtTimestamp
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
        - name: timestamp
          in: path
          required: true
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Object at specified time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectEntity'
  /api/objects/{uuid}/compare:
    get:
      tags:
        - Objects
      summary: Compare object versions
      operationId: compareObjectVersions
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
        - name: version1
          in: query
          required: true
          schema:
            type: string
        - name: version2
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Version comparison results
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  changes:
                    type: object
  /api/objects/{uuid}/restore:
    post:
      tags:
        - Objects
      summary: Restore object to previous version
      operationId: restoreObject
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                version:
                  type: string
                timestamp:
                  type: string
                  format: date-time
              oneOf:
                - required:
                    - version
                - required:
                    - timestamp
      responses:
        '200':
          description: Object restored successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectEntity'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Basic authentication using username and password. Not recommended for
        production use.
    oauth2:
      type: oauth2
      description: OAuth2 authentication using Nextcloud's authentication server.
      flows:
        authorizationCode:
          authorizationUrl: /apps/oauth2/authorize
          tokenUrl: /apps/oauth2/api/v1/token
          refreshUrl: /apps/oauth2/api/v1/token
          scopes:
            read: Read access to all resources
            write: Write access to all resources
  schemas:
    Register:
      type: object
      properties:
        uuid:
          type: string
        title:
          type: string
        description:
          type: string
        version:
          type: string
        schemas:
          type: array
          items:
            type: string
    Schema:
      type: object
      properties:
        uuid:
          type: string
        title:
          type: string
        description:
          type: string
        version:
          type: string
        properties:
          type: object
    Source:
      type: object
      properties:
        uuid:
          type: string
        title:
          type: string
        version:
          type: string
        description:
          type: string
        databaseUrl:
          type: string
        type:
          type: string
    ObjectEntity:
      type: object
      properties:
        id:
          type: integer
          example: 123
        uuid:
          type: string
          example: 123e4567-e89b-12d3-a456-426614174000
        uri:
          type: string
          example: /api/objects/123e4567-e89b-12d3-a456-426614174000
        version:
          type: string
          example: '1.0'
        register:
          type: integer
          example: 123
        schema:
          type: integer
          example: 123
        object:
          type: object
          example:
            firstName: John
            lastName: Doe
            birthDate: '1980-01-15'
            email: john.doe@example.com
            address:
              street: 123 Main St
              city: Anytown
              postalCode: '12345'
              country: USA
            phoneNumbers:
              - type: mobile
                number: 555-123-4567
            spouse: 123e4567-e89b-12d3-a456-426614174000
        files:
          type: array
          items:
            type: string
          example:
            - '123'
            - '124'
        relations:
          type: array
          items:
            type: string
          example:
            spouse: 123e4567-e89b-12d3-a456-426614174000
        locked:
          oneOf:
            - $ref: '#/components/schemas/Lock'
            - type: 'null'
          description: Contains either a lock object or the value null
        deleted:
          oneOf:
            - $ref: '#/components/schemas/Deletion'
            - type: 'null'
          description: Contains either a deletion object or the value null
        owner:
          type: string
          example: user-12345
    Lock:
      type: object
      description: >-
        Lock information object for concurrent access control. Objects can be
        locked to prevent concurrent editing, ensuring data integrity in
        multi-user environments.
      properties:
        user:
          type: string
          description: User ID that created the lock
          example: user_id
        process:
          type: string
          description: Optional process name associated with the lock
          example: optional_process_name
        created:
          type: string
          format: date-time
          description: Timestamp when the lock was created
          example: timestamp
        duration:
          type: integer
          description: Duration of the lockin seconds
          example: seconds
        expiration:
          type: string
          format: date-time
          description: Timestamp when the object expires (is autmaticly removed)
          example: timestamp
    Deletion:
      type: object
      properties:
        deleted:
          type: string
          format: date-time
          description: When the object was marked as deleted
          example: '2023-01-01T00:00:00Z'
        deletedBy:
          type: string
          description: User ID who performed the deletion
          example: user-12345
        deletedReason:
          type: string
          description: Optional reason for deletion
          example: No longer needed
        retentionPeriod:
          type: integer
          description: How long to keep the deleted object (in days)
          example: 30
          default: 30
        purgeDate:
          type: string
          format: date-time
          description: When the object will be permanently deleted
          example: '2023-01-31T00:00:00Z'
    '@self':
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the object
          example: 123
        uuid:
          type: string
          description: >-
            Unique universal identifier for globally unique object
            identification
          example: 123e4567-e89b-12d3-a456-426614174000
        uri:
          type: string
          description: Uniform Resource Identifier for unique addressable location
          example: /api/objects/123e4567-e89b-12d3-a456-426614174000
        version:
          type: string
          description: Semantic version number to track object versions
          example: '1.0'
        register:
          type: integer
          description: Register identifier for object categorization/grouping
          example: 123
        schema:
          type: integer
          description: Schema identifier for data validation reference
          example: 123
        textRepresentation:
          type: string
          description: Text representation of object for search and display optimization
          example: 'John Doe, born 1980-01-15, email: john.doe@example.com'
        locked:
          oneOf:
            - $ref: '#/components/schemas/Lock'
            - type: 'null'
          description: Contains either a lock object or the value null
        deleted:
          oneOf:
            - $ref: '#/components/schemas/Deletion'
            - type: 'null'
          description: Contains either a deletion object or the value null
        owner:
          type: string
          description: Nextcloud user identifier for object ownership
          example: user-12345
        authorization:
          type: object
          description: Authorization rules for access control configuration
          example:
            read: true
            write: false
        updated:
          type: string
          format: date-time
          description: Last modification timestamp for change tracking
          example: '2023-05-20T10:15:00Z'
        created:
          type: string
          format: date-time
          description: Creation timestamp for lifecycle management
          example: '2023-02-15T14:30:00Z'
        folder:
          type: string
          description: Storage folder path for file organization
          example: /persons/john-doe
        files:
          type: array
          description: Array of related files to track associated files
          items:
            $ref: '#/components/schemas/File'
          example:
            - id: 123
              uuid: 123e4567-e89b-12d3-a456-426614174000
              filename: profile.jpg
              downloadUrl: https://example.com/download/123
              shareUrl: https://example.com/share/123
              accessUrl: https://example.com/access/123
              extension: jpg
              checksum: abc123
              source: 1
              userId: user-12345
              base64: base64encodedstring
              filePath: /files/profile.jpg
              created: '2023-02-15T14:30:00Z'
              updated: '2023-05-20T10:15:00Z'
            - id: 124
              uuid: 123e4567-e89b-12d3-a456-426614174001
              filename: resume.pdf
              downloadUrl: https://example.com/download/124
              shareUrl: https://example.com/share/124
              accessUrl: https://example.com/access/124
              extension: pdf
              checksum: def456
              source: 1
              userId: user-12345
              base64: base64encodedstring
              filePath: /files/resume.pdf
              created: '2023-02-16T14:30:00Z'
              updated: '2023-05-21T10:15:00Z'
        relations:
          type: array
          description: Array of related object IDs to track object relationships
          items:
            type: string
          example:
            spouse: 123e4567-e89b-12d3-a456-426614174000
        errors:
          type: array
          description: >-
            Array of error messages encounterd during the rendering process of
            this object
          items:
            type: string
          example:
            - Property 'spouse' could not be extended because it does not exist.
    SerializeEntity:
      type: object
      properties:
        object:
          type: object
        '@self':
          $ref: '#/components/schemas/@self'
    File:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier of the file in Nextcloud
          example: 123
        uuid:
          type: string
          description: Unique identifier for the file
          example: 123e4567-e89b-12d3-a456-426614174000
        filename:
          type: string
          description: Name of the file
          example: profile.jpg
        downloadUrl:
          type: string
          format: uri
          description: Direct download URL for the file
          example: https://example.com/download/123
        shareUrl:
          type: string
          format: uri
          description: URL to access the file via share link
          example: https://example.com/share/123
        accessUrl:
          type: string
          format: uri
          description: URL to access the file
          example: https://example.com/access/123
        extension:
          type: string
          description: File extension
          example: jpg
        checksum:
          type: string
          description: ETag hash for file versioning
          example: abc123
        source:
          type: integer
          description: Source identifier
          example: 1
        userId:
          type: string
          description: ID of the user who owns the file
          example: user-12345
        base64:
          type: string
          description: Base64 encoded content of the file
          example: base64encodedstring
        filePath:
          type: string
          description: Full path to the file in Nextcloud
          example: /files/profile.jpg
        created:
          type: string
          format: date-time
          description: ISO 8601 timestamp when file was first shared
          example: '2023-02-15T14:30:00Z'
        updated:
          type: string
          format: date-time
          description: ISO 8601 timestamp of last modification
          example: '2023-05-20T10:15:00Z'
    AuditTrail:
      type: object
      properties:
        uuid:
          type: string
          description: Unique identifier for the audit entry
          example: 550e8400-e29b-41d4-a716-446655440000
        schema:
          type: integer
          description: Schema ID of the modified object
          example: 42
        register:
          type: integer
          description: Register ID of the modified object
          example: 123
        object:
          type: integer
          description: Object ID that was modified
          example: 456
        action:
          type: string
          description: Type of change that occurred
          example: create
        changed:
          type: object
          description: Array of modified fields with old/new values
          example:
            name:
              old: John
              new: Jane
        user:
          type: string
          description: ID of the user who made the change
          example: admin
        userName:
          type: string
          description: Display name of the user
          example: Administrator
        session:
          type: string
          description: Session ID when change occurred
          example: sess_89d7h2
        request:
          type: string
          description: Request ID for tracing
          example: req_7d8h3j
        ipAddress:
          type: string
          description: IP address of the request
          example: 192.168.1.1
        version:
          type: string
          description: Object version after change
          example: 1.0.0
        created:
          type: string
          format: date-time
          description: Timestamp of the change
          example: '2024-03-15T14:30:00Z'
        processingActivity:
          type: string
          description: The processing activity from the registry
        processing:
          type: string
          description: The specific task being performed
        operation:
          type: string
          description: The step in the processing task
        legalBasis:
          type: string
          description: Legal basis for the processing
        retentionPeriod:
          type: string
          description: Retention period for the data
        executor:
          type: string
          description: The system or person executing the action
        system:
          type: string
          description: The system where the action occurred
        dataSource:
          type: string
          description: The source of the data