DRS write support

CLAUDE.md

@@ -0,0 +1,90 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This repository contains the GA4GH Data Repository Service (DRS) API schema definitions. DRS provides a generic interface to data repositories, allowing data consumers to access data in a standardized way regardless of where it's stored. The API defines a system for mapping logical IDs to means for physically retrieving data.
+
+## Development Commands
+
+### Documentation Building
+```bash
+# Install required tools
+npm install -g @redocly/openapi-cli redoc-cli
+npm install -g @ga4gh/[email protected]
+
+# Build documentation (used in CI)
+gh-openapi-docs
+```
+
+### OpenAPI Validation
+```bash
+# Validate OpenAPI specification
+openapi-cli validate openapi/data_repository_service.openapi.yaml
+```
+
+## Architecture & Structure
+
+### Core Components
+
+- **`openapi/data_repository_service.openapi.yaml`**: Main OpenAPI 3.0.3 specification file
+- **`openapi/components/`**: Reusable OpenAPI components organized by type:
+  - `schemas/`: Core data models (DrsObject, AccessMethod, AccessURL, etc.)
+  - `responses/`: Standard HTTP response definitions
+  - `parameters/`: Reusable path/query parameters
+  - `paths/`: API endpoint definitions
+- **`openapi/tags/`**: Markdown documentation files for API sections
+
+### Key Data Models
+
+- **DrsObject**: Core entity representing a data object with metadata, checksums, and access methods
+- **AccessMethod**: Defines how to access data (s3, gs, https, file, etc.) with URLs or access IDs
+- **AccessURL**: Contains the actual URL and optional headers for data retrieval
+- **Checksum**: Data integrity verification information
+
+### API Endpoints Structure
+
+- `/objects/{object_id}`: GET/POST/OPTIONS for object metadata
+- `/objects/{object_id}/access/{access_id}`: GET/POST for access URLs
+- `/bulkobjects/{object_id}`: Bulk operations for multiple objects
+- `/service-info`: Service metadata endpoint
+
+## Development Workflow
+
+### Branch Strategy (HubFlow)
+
+- **`master`**: Production releases only
+- **`develop`**: Stable development branch (all PRs target this)
+- **Feature branches**: `feature/issue-<number>-<description>`
+- **Release branches**: `release/<version>` or `release/drs-<version>`
+
+### Making Changes
+
+1. Create issue in GitHub to track work
+2. Create feature branch from `develop` following naming convention
+3. Make changes to OpenAPI YAML files
+4. Travis CI will automatically build and validate on push
+5. Submit PR to `develop` branch
+6. PRs require review and driver project voting for approval
+
+### File Organization
+
+- OpenAPI components are split into separate YAML files for maintainability
+- Documentation is embedded in markdown files referenced from the main spec
+- All schema changes must include proper documentation updates
+
+## CI/CD Pipeline
+
+- **Travis CI** builds documentation and validates OpenAPI spec
+- **GitHub Pages** deployment for documentation hosting
+- Preview builds available for all feature branches at: `ga4gh.github.io/data-repository-service-schemas/preview/<branch-name>/`
+- Production docs at: `ga4gh.github.io/data-repository-service-schemas/docs/`
+
+## Validation & Standards
+
+- OpenAPI 3.0.3 specification compliance required
+- Two-space indentation, no tabs
+- 80-character line limit
+- All new schemas require normative documentation
+- Security considerations must be documented for any auth-related changes

openapi/components/responses/400BadRequest.yaml

@@ -2,4 +2,20 @@ description: The request is malformed.
 content:
   application/json:
     schema:
-      $ref: '../schemas/Error.yaml'
+      $ref: '../schemas/Error.yaml'
+    examples:
+      missing_required_field:
+        summary: Missing required field
+        value:
+          msg: "Missing required field: 'size'"
+          status_code: 400
+      invalid_checksum:
+        summary: Invalid checksum format
+        value:
+          msg: "Invalid checksum format. Expected format: '{algorithm}:{checksum}'"
+          status_code: 400
+      negative_size:
+        summary: Invalid size value
+        value:
+          msg: "Size must be a positive integer"
+          status_code: 400

openapi/components/responses/409Conflict.yaml

@@ -0,0 +1,17 @@
+description: |-
+  The request conflicts with the current state of the resource
+content:
+  application/json:
+    schema:
+      $ref: '../schemas/Error.yaml'
+    examples:
+      object_exists:
+        summary: Object already exists
+        value:
+          msg: "DRS object with ID 'abc123' already exists"
+          status_code: 409
+      wrong_state:
+        summary: Object in wrong state for operation
+        value:
+          msg: "Cannot finalize object in state 'available'. Object must be in 'pending' state."
+          status_code: 409

openapi/components/responses/422UnprocessableEntity.yaml

@@ -0,0 +1,17 @@
+description: |-
+  The request was well-formed but was unable to be followed due to semantic errors (e.g., checksum validation failed)
+content:
+  application/json:
+    schema:
+      $ref: '../schemas/Error.yaml'
+    examples:
+      checksum_mismatch:
+        summary: Checksum validation failed
+        value:
+          msg: "Checksum validation failed: expected md5:d41d8cd98f00b204e9800998ecf8427e but got md5:5d41402abc4b2a76b9719d911017c592"
+          status_code: 422
+      invalid_storage_location:
+        summary: Invalid storage location
+        value:
+          msg: "Storage location 'invalid-location' does not exist or is not accessible"
+          status_code: 422

openapi/components/schemas/AuthorizedLocation.yaml

@@ -0,0 +1,29 @@
+type: object
+required:
+  - storage_location_id
+  - permissions
+properties:
+  storage_location_id:
+    type: string
+    description: The storage location identifier this authorization applies to
+    example: "us-east-1-s3"
+  permissions:
+    type: array
+    items:
+      type: string
+      enum:
+        - create
+        - update
+        - delete
+    description: Write permissions granted for this storage location
+    example: ["create", "update", "delete"]
+  quota_remaining:
+    type: integer
+    format: int64
+    description: Remaining storage quota in bytes for this location (null means no quota limit)
+    example: 1073741824000
+  quota_total:
+    type: integer
+    format: int64
+    description: Total storage quota in bytes for this location
+    example: 5497558138880

openapi/components/schemas/CreateObjectRequest.yaml

@@ -0,0 +1,43 @@
+type: object
+required:
+  - size
+  - checksums
+  - target_storage_location
+properties:
+  name:
+    type: string
+    description: |-
+      A string that can be used to name a `DrsObject`.
+      This string is made up of uppercase and lowercase letters, decimal digits, hyphen, period, and underscore [A-Za-z0-9.-_]. See http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282[portable filenames].
+    example: "sample-data.bam"
+  size:
+    type: integer
+    format: int64
+    description: Size of the object in bytes
+    example: 1073741824
+  checksums:
+    type: array
+    items:
+      $ref: './Checksum.yaml'
+    minItems: 1
+    description: The checksums of the object. At least one checksum must be provided.
+  target_storage_location:
+    type: string
+    description: The storage location where this object should be uploaded
+    example: "us-east-1-s3"
+  description:
+    type: string
+    description: A human readable description of the object
+    example: "Sample BAM file from analysis pipeline"
+  mime_type:
+    type: string
+    description: A string providing the mime-type of the object
+    example: "application/octet-stream"
+  aliases:
+    type: array
+    items:
+      type: string
+    description: A list of strings that can be used to find other metadata about this object from external metadata sources
+  version:
+    type: string
+    description: A string representing a version of this object

openapi/components/schemas/CreateObjectResponse.yaml

@@ -0,0 +1,26 @@
+type: object
+required:
+  - object
+  - upload_url
+properties:
+  object:
+    allOf:
+      - $ref: './DrsObject.yaml'
+      - type: object
+        properties:
+          state:
+            type: string
+            enum:
+              - pending
+              - uploading
+              - available
+              - failed
+              - deleted
+            description: Current state of the DRS object
+            example: "pending"
+          target_storage_location:
+            type: string
+            description: The target storage location for this object
+            example: "us-east-1-s3"
+  upload_url:
+    $ref: './UploadURL.yaml'

openapi/components/schemas/DrsService.yaml

@@ -29,6 +29,8 @@ properties:
       totalObjectSize:
         type: integer
         description: The total size of all objects in this DRS service in bytes.  As a general best practice, file bytes are counted for each unique file and not cloud mirrors or other redundant copies.
+      writeCapabilities:
+        $ref: './WriteCapabilities.yaml'
 
 
 

openapi/components/schemas/FinalizeObjectRequest.yaml

@@ -0,0 +1,24 @@
+type: object
+required:
+  - uploaded_locations
+properties:
+  uploaded_locations:
+    type: array
+    items:
+      type: object
+      required:
+        - storage_location_id
+        - checksums
+      properties:
+        storage_location_id:
+          type: string
+          description: The storage location where data was uploaded
+          example: "us-east-1-s3"
+        checksums:
+          type: array
+          items:
+            $ref: './Checksum.yaml'
+          minItems: 1
+          description: Checksums computed after upload to verify integrity
+    minItems: 1
+    description: List of storage locations where the object was successfully uploaded

openapi/components/schemas/StorageLocation.yaml

@@ -0,0 +1,38 @@
+type: object
+required:
+  - id
+  - type
+properties:
+  id:
+    type: string
+    description: Unique identifier for this storage location
+    example: "us-east-1-s3"
+  type:
+    type: string
+    enum:
+      - s3
+      - gs
+      - azure
+      - file
+      - ftp
+      - gsiftp
+      - globus
+      - https
+    description: Storage backend type
+    example: "s3"
+  region:
+    type: string
+    description: Geographic region or availability zone
+    example: "us-east-1"
+  description:
+    type: string
+    description: Human-readable description of this storage location
+    example: "AWS S3 US East 1"
+  public:
+    type: boolean
+    description: Whether this location allows public read access without authentication
+    example: false
+  endpoint:
+    type: string
+    description: Custom endpoint URL for this storage location (for non-standard cloud providers)
+    example: "https://s3.us-east-1.amazonaws.com"

openapi/components/schemas/UpdateObjectRequest.yaml

@@ -0,0 +1,38 @@
+type: object
+properties:
+  name:
+    type: string
+    description: |-
+      A string that can be used to name a `DrsObject`.
+      This string is made up of uppercase and lowercase letters, decimal digits, hyphen, period, and underscore [A-Za-z0-9.-_]. See http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282[portable filenames].
+    example: "updated-sample-data.bam"
+  size:
+    type: integer
+    format: int64
+    description: New size of the object in bytes (triggers content update)
+    example: 2147483648
+  checksums:
+    type: array
+    items:
+      $ref: './Checksum.yaml'
+    description: New checksums of the object (triggers content update)
+  target_storage_location:
+    type: string
+    description: New target storage location (triggers content update)
+    example: "europe-gcs"
+  description:
+    type: string
+    description: A human readable description of the object
+    example: "Updated sample BAM file from analysis pipeline"
+  mime_type:
+    type: string
+    description: A string providing the mime-type of the object
+    example: "application/octet-stream"
+  aliases:
+    type: array
+    items:
+      type: string
+    description: A list of strings that can be used to find other metadata about this object from external metadata sources
+  version:
+    type: string
+    description: A string representing a version of this object