feat!: add File entity support and RO-Crate metadata endpoint

BREAKING CHANGE: Remove /entity/{id}/file/{fileId} endpoint in favour of /entity/{id}/file

- Add http://pcdm.org/models#File entity type to support individual files
- Remove /entity/{id}/file/{fileId} endpoint (breaking change)
- Add /entity/{id}/file endpoint for accessing File entity content
- Add /entity/{id}/crate endpoint to retrieve RO-Crate JSON-LD metadata
- Add InvalidEntityTypeError schema for entity type validation
- Update documentation with File entity examples and migration guide
- Remove http://schema.org/MediaObject from EntityType enum

The new /entity/{id}/file endpoint only works with File entities and returns
a 400 error with INVALID_ENTITY_TYPE code for Collection or Object entities.

The new /entity/{id}/crate endpoint works with all entity types and returns
the complete RO-Crate metadata conforming to the RO-Crate specification.

Author: johnf

docs/getting-started/overview.md

@@ -99,6 +99,30 @@ curl -X POST https://data.ldaca.edu.au/api/search \
   }'
 ```
 
+### Access File Content
+
+For File entities, you can directly access the file content:
+
+```bash
+curl https://data.ldaca.edu.au/api/entity/https%3A%2F%2Fcatalog.paradisec.org.au%2Frepository%2FLRB%2F001%2Ffile.wav/file
+```
+
+This endpoint supports:
+- Content disposition (inline or attachment)
+- Custom filenames
+- HTTP range requests for partial content
+- Redirects to file storage locations
+
+### Get RO-Crate Metadata
+
+Retrieve the raw RO-Crate JSON-LD metadata for any entity:
+
+```bash
+curl https://data.ldaca.edu.au/api/entity/https%3A%2F%2Fcatalog.paradisec.org.au%2Frepository%2FLRB%2F001/crate
+```
+
+This returns the complete RO-Crate metadata conforming to the RO-Crate specification.
+
 ## Understanding Responses
 
 ### Success Responses

docs/getting-started/use-cases.md

@@ -96,31 +96,31 @@ curl -X POST https://data.ldaca.edu.au/api/search \
   }'
 ```
 
-## 3. Downloading Files from Entities
+## 3. Working with File Entities
 
-### Getting File Information
+### Accessing File Content
 
-First, get entity details to see available files:
+File entities (entityType: `http://pcdm.org/models#File`) can be accessed directly:
 
 ```bash
-curl "https://data.ldaca.edu.au/api/entity/https%3A%2F%2Fcatalog.paradisec.org.au%2Frepository%2FLRB%2F001"
+# Direct file download
+curl "https://data.ldaca.edu.au/api/entity/https%3A%2F%2Fcatalog.paradisec.org.au%2Frepository%2FLRB%2F001%2Frecording.wav/file" -o recording.wav
 ```
 
-### Downloading Files
+### Download as Attachment
 
-Download a specific file:
+Force download with a custom filename:
 
 ```bash
-# Direct download
-wget "https://data.ldaca.edu.au/api/entity/https%3A%2F%2Fcatalog.paradisec.org.au%2Frepository%2FLRB%2F001/file/recording.wav"
+curl "https://data.ldaca.edu.au/api/entity/https%3A%2F%2Fcatalog.paradisec.org.au%2Frepository%2FLRB%2F001%2Frecording.wav/file?disposition=attachment&filename=my-recording.wav"
 ```
 
-### Getting Download URLs
+### Getting File Location
 
-Instead of direct download, get the file location:
+Get the file location without downloading:
 
 ```bash
-curl "https://data.ldaca.edu.au/api/entity/https%3A%2F%2Fcatalog.paradisec.org.au%2Frepository%2FLRB%2F001/file/recording.wav?noRedirect=true"
+curl "https://data.ldaca.edu.au/api/entity/https%3A%2F%2Fcatalog.paradisec.org.au%2Frepository%2FLRB%2F001%2Frecording.wav/file?noRedirect=true"
 ```
 
 **Response:**
@@ -131,22 +131,74 @@ curl "https://data.ldaca.edu.au/api/entity/https%3A%2F%2Fcatalog.paradisec.org.a
 }
 ```
 
-## 4. Paginating Through Large Result Sets
+### Partial Content Download
+
+Use HTTP range requests for streaming or resuming downloads:
+
+```bash
+# Download first 1KB
+curl -H "Range: bytes=0-1023" \
+  "https://data.ldaca.edu.au/api/entity/https%3A%2F%2Fcatalog.paradisec.org.au%2Frepository%2FLRB%2F001%2Frecording.wav/file"
+```
+
+## 4. Retrieving RO-Crate Metadata
+
+### Get Complete RO-Crate JSON-LD
+
+Access the raw RO-Crate metadata for any entity:
+
+```bash
+curl "https://data.ldaca.edu.au/api/entity/https%3A%2F%2Fcatalog.paradisec.org.au%2Frepository%2FLRB%2F001/crate"
+```
+
+**Response:**
+
+```json
+{
+  "@context": "https://w3id.org/ro/crate/1.1/context",
+  "@graph": [
+    {
+      "@id": "ro-crate-metadata.json",
+      "@type": "CreativeWork",
+      "conformsTo": {
+        "@id": "https://w3id.org/ro/crate/1.1"
+      },
+      "about": {
+        "@id": "./"
+      }
+    },
+    {
+      "@id": "./",
+      "@type": "Dataset",
+      "name": "Recordings of West Alor languages",
+      "description": "A compilation of recordings featuring various West Alor languages"
+    }
+  ]
+}
+```
+
+This is useful for:
+- Validating RO-Crate compliance
+- Accessing extended metadata not exposed in the entity API
+- Archival and preservation workflows
+- Integration with RO-Crate tools
+
+## 5. Paginating Through Large Result Sets
 
 ### Basic Pagination
 
 ```bash
 # First page
 curl "https://data.ldaca.edu.au/api/entities?limit=100&offset=0"
 
-# Second page  
+# Second page
 curl "https://data.ldaca.edu.au/api/entities?limit=100&offset=100"
 
 # Third page
 curl "https://data.ldaca.edu.au/api/entities?limit=100&offset=200"
 ```
 
-## 5. Working with Communication Modes
+## 6. Working with Communication Modes
 
 Language archives often categorise data by communication mode:
 

docs/intro.md

@@ -54,8 +54,9 @@ engines.
 ### 📊 **Rich Metadata**
 
 - Complete RO-Crate entity information
-- Hierarchical collection browsing
-- File access and download
+- Hierarchical collection browsing (Collections, Objects, and Files)
+- File entity access and download
+- Access to raw RO-Crate metadata
 - Conformance to LDAC profiles
 
 ### 🚀 **Developer Friendly**
@@ -78,9 +79,10 @@ The RO-Crate API is already in use by several major research data repositories:
 ### Entity Management
 
 - List entities with filtering and pagination
-- Retrieve detailed entity information
+- Retrieve detailed entity information for Collections, Objects, and Files
 - Navigate collection hierarchies
-- Access files and media
+- Access file content directly through File entities
+- Retrieve raw RO-Crate JSON-LD metadata
 
 ### Advanced Search
 

openapi.yaml

@@ -179,33 +179,26 @@ paths:
         "500":
           $ref: "#/components/responses/InternalServerErrorResponse"
 
-  /entity/{id}/file/{fileId}:
+  /entity/{id}/file:
     get:
       tags:
         - entities
-      summary: Get a file
+      summary: Get file content
       description: |
         ### File Access
-        Retrieve an individual file that is part of a given entity's RO-Crate. The file can be returned inline (e.g., displayed in the browser) or as an attachment for download (e.g., prompting a save dialog), based on the disposition.
-        The API can serve the file or redirect to the location of the file
-      operationId: getEntityOpen
+        Retrieve the file content for an entity of type File. The file can be returned inline (e.g., displayed in the browser) or as an attachment for download (e.g., prompting a save dialog), based on the disposition parameter.
+        The API can serve the file directly or redirect to the location of the file.
+
+        This endpoint only works for entities with entityType `http://pcdm.org/models#File`. For Collection or Object entities, a 400 error will be returned.
+      operationId: getEntityFile
       parameters:
         - name: id
           in: path
           required: true
-          description: The RO-Crate entity ID to which the file belongs.
-          example: https://catalog.paradisec.org.au/repository/LRB/001
+          description: The RO-Crate entity ID of the File entity.
+          example: https://catalog.paradisec.org.au/repository/LRB/001/file.wav
           schema:
             $ref: "#/components/schemas/Id"
-        - name: fileId
-          in: path
-          required: true
-          description: The path or identifier of the file within the entity’s crate.
-          example: filename.wav
-          schema:
-            type: string
-            maxLength: 255
-            pattern: '^[a-zA-Z0-9._\-/\s]+$'
         - name: disposition
           in: query
           description: The HTTP Content-Disposition for how the file should be handled by the client.
@@ -288,17 +281,17 @@ paths:
         "302":
           description: Redirects to file location
         "400":
-          description: Bad Request - Invalid parameters
+          description: Bad Request - Invalid parameters or entity is not a File type
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ValidationError"
+                $ref: "#/components/schemas/InvalidEntityTypeError"
         "401":
           $ref: "#/components/responses/UnauthorizedResponse"
         "403":
           $ref: "#/components/responses/ForbiddenResponse"
         "404":
-          description: Entity or file not found
+          description: Entity not found
           content:
             application/json:
               schema:
@@ -321,6 +314,60 @@ paths:
         "500":
           $ref: "#/components/responses/InternalServerErrorResponse"
 
+  /entity/{id}/crate:
+    get:
+      tags:
+        - entities
+      summary: Get RO-Crate metadata
+      description: |
+        ### RO-Crate Metadata
+        Retrieve the complete RO-Crate JSON-LD metadata for an entity. This returns the raw RO-Crate representation, which includes all metadata conforming to the RO-Crate specification.
+
+        This endpoint works for any entity type (Collection, Object, or File) and returns the associated ro-crate-metadata.json content.
+      operationId: getEntityCrate
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: The RO-Crate entity ID.
+          example: https://catalog.paradisec.org.au/repository/LRB/001
+          schema:
+            $ref: "#/components/schemas/Id"
+      responses:
+        "200":
+          description: Returns the RO-Crate JSON-LD metadata
+          content:
+            application/ld+json:
+              schema:
+                type: object
+                description: RO-Crate metadata conforming to the RO-Crate specification
+                example:
+                  "@context": "https://w3id.org/ro/crate/1.1/context"
+                  "@graph":
+                    - "@id": "ro-crate-metadata.json"
+                      "@type": "CreativeWork"
+                      conformsTo:
+                        "@id": "https://w3id.org/ro/crate/1.1"
+                      about:
+                        "@id": "./"
+                    - "@id": "./"
+                      "@type": "Dataset"
+                      name: "Recordings of West Alor languages"
+        "401":
+          $ref: "#/components/responses/UnauthorizedResponse"
+        "403":
+          $ref: "#/components/responses/ForbiddenResponse"
+        "404":
+          description: Entity not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/NotFoundError"
+        "429":
+          $ref: "#/components/responses/RateLimitResponse"
+        "500":
+          $ref: "#/components/responses/InternalServerErrorResponse"
+
   /search:
     post:
       tags:
@@ -665,9 +712,9 @@ components:
       enum:
         - http://pcdm.org/models#Collection
         - http://pcdm.org/models#Object
-        - http://schema.org/MediaObject
+        - http://pcdm.org/models#File
         - http://schema.org/Person
-      description: An enumerated type describing the nature of the entity, such as a collection or object
+      description: An enumerated type describing the nature of the entity, such as a collection, object, or file
     Order:
       type: string
       enum:
@@ -841,6 +888,30 @@ components:
                 message:
                   example: The requested entity was not found
 
+    InvalidEntityTypeError:
+      allOf:
+        - $ref: "#/components/schemas/ErrorResponse"
+        - type: object
+          properties:
+            error:
+              type: object
+              properties:
+                code:
+                  enum: [INVALID_ENTITY_TYPE]
+                message:
+                  example: This operation is only valid for File entities
+                details:
+                  type: object
+                  properties:
+                    entityType:
+                      type: string
+                      description: The actual entity type of the requested entity
+                      example: http://pcdm.org/models#Collection
+                    expectedType:
+                      type: string
+                      description: The expected entity type for this operation
+                      example: http://pcdm.org/models#File
+
     RateLimitError:
       allOf:
         - $ref: "#/components/schemas/ErrorResponse"