diff --git a/extensions/data-transfer/portability-data-transfer-generic/README.md b/extensions/data-transfer/portability-data-transfer-generic/README.md
index 55572dd43..af653ee92 100644
--- a/extensions/data-transfer/portability-data-transfer-generic/README.md
+++ b/extensions/data-transfer/portability-data-transfer-generic/README.md
@@ -79,7 +79,9 @@ Your endpoint should return a 20x status code if the resource has been created,
For basic data-types the Importer will send a POST request with a `Content-Type: application/json` header. The body of the POST request will be a UTF-8 encoded JSON payload conforming to the relevant data-type schema detailed in the [Schemas](#schemas) section.
-For example, below is a full request of a SOCIAL-POSTS item (JSON formatted for readability)
+For example, below is a full request of a SOCIAL-POSTS item (JSON formatted for readability). This example is also
+in social-post-payload-example.json, which can be validated against
+payload-schema.json and its subschemas.
```http
POST /import/social-posts HTTP/1.1
@@ -103,7 +105,7 @@ Authorization: Bearer accessToken
"@type": "SocialActivityActor",
"id": "321",
"name": "Steve",
- "url": null
+ "url": "http://example.org/actor/Steve"
}
},
"activity": {
@@ -117,7 +119,7 @@ Authorization: Bearer accessToken
"type": "IMAGE",
"url": "foo.com",
"name": "Foo",
- "content": null
+ "content": "Example"
}
],
"location": {
@@ -128,7 +130,7 @@ Authorization: Bearer accessToken
},
"title": "Hello world!",
"content": "Hi there",
- "url": null
+ "url": "http://example.org/post/foo"
}
}
}
@@ -185,39 +187,10 @@ serviceConfig:
## Schemas
-Below are the [JSON schemas](https://json-schema.org/specification) for each supported vertical.
+[JSON schemas](https://json-schema.org/specification) are defined for each supported vertical.
-All POST requests containing data to be imported are wrapped in a top-level `GenericPayload` wrapper.
-
-```json
-{
- "$schema": "https://json-schema.org/draft/2020-12/schema",
- "type": "object",
- "properties": {
- "apiVersion": {
- "type": "string"
- },
- "payload": {
- "type": "object",
- "description": "The inner payload, which contains data from one of the described data verticals"
- },
- "schemaSource": {
- "type": "string",
- "description": "The source file containing the schema definition. The whole path relative to this package is not needed,
- so the value may be '.../SocialPostsSerializer.java' rather than './src/main/java/org/datatransferproject/datatransfer/generic/SocialPostsSerializer'."
- },
- "@type": {
- "const": "GenericPayload"
- }
- },
- "required": [
- "@type",
- "schemaSource",
- "apiVersion",
- "payload"
- ]
-}
-```
+All POST requests containing data to be imported are wrapped in a top-level `GenericPayload` wrapper with
+the Payload schema.
### MEDIA
@@ -229,125 +202,12 @@ Albums are conventionally imported before the photos and videos contained in the
#### Basic Data Types
-The only basic data type exposed for MEDIA data is `Album`, which contains metadata about an album.
-
-```json
-{
- "$schema" : "https://json-schema.org/draft/2020-12/schema",
- "type": "object",
- "properties": {
- "description": {
- "type": "string"
- },
- "id": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "@type": {
- "const": "Album"
- }
- },
- "required": [
- "@type",
- "id",
- "name"
- ]
-}
-```
+The only basic data type exposed for MEDIA data is `Album`, using the Album schema.
#### File-based Data Types
-The `Photo` and `Video` data types are sent as file-based data containing metadata described below in the JSON part of the payload.
-
-```json
-{
- "$schema" : "https://json-schema.org/draft/2020-12/schema",
- "$defs": {
- "FavoriteInfo": {
- "type": "object",
- "properties": {
- "favorite": {
- "type": "boolean"
- },
- "lastUpdateTime": {
- "type": "string",
- "format": "date-time"
- },
- "@type": {
- "const": "FavoriteInfo"
- }
- },
- "required": [
- "@type",
- "favorite",
- "lastUpdateTime"
- ]
- }
- },
- "anyOf": [
- {
- "type": "object",
- "properties": {
- "albumId": {
- "type": "string"
- },
- "description": {
- "type": "string"
- },
- "favoriteInfo": {
- "$ref": "#/$defs/FavoriteInfo"
- },
- "name": {
- "type": "string"
- },
- "uploadedTime": {
- "type": "string",
- "format": "date-time"
- },
- "@type": {
- "const": "Video"
- }
- },
- "required": [
- "@type",
- "albumId",
- "name"
- ]
- },
- {
- "type": "object",
- "properties": {
- "albumId": {
- "type": "string"
- },
- "description": {
- "type": "string"
- },
- "favoriteInfo": {
- "$ref": "#/$defs/FavoriteInfo"
- },
- "name": {
- "type": "string"
- },
- "uploadedTime": {
- "type": "string",
- "format": "date-time"
- },
- "@type": {
- "const": "Photo"
- }
- },
- "required": [
- "@type",
- "albumId",
- "name"
- ]
- }
- ]
-}
-```
+The `Photo` and `Video` data types are sent as file-based data containing metadata described in the photo and video schema.
#### PHOTOS and VIDEOS
@@ -363,61 +223,12 @@ Folders are conventionally imported before any of their containing data, which m
#### Basic Data Types
-The only basic data type exposed for BLOBS data is `Folder`, which describes a folder containing other folders and/or files.
-
-```json
-{
- "$schema": "https://json-schema.org/draft/2020-12/schema",
- "type": "object",
- "properties": {
- "path": {
- "type": "string",
- "description": "Full path of the folder to be created"
- },
- "@type": {
- "const": "Folder"
- }
- },
- "required": [
- "@type",
- "path"
- ]
-}
-```
+The only basic data type exposed for BLOBS data is `Folder`, which describes a folder containing other folders and/or files
+in the folder schema.
#### File-based Data Types
-The only file-based data type exposed for BLOBS data is `File`, which describes an arbitrary file in a folder. The file's metadata will be describes in the JSON part of the payload, with the below schema.
-
-```json
-{
- "$schema": "https://json-schema.org/draft/2020-12/schema",
- "type": "object",
- "properties": {
- "dateModified": {
- "type": [
- "string",
- "null"
- ],
- "format": "date-time"
- },
- "folder": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "@type": {
- "const": "File"
- }
- },
- "required": [
- "@type",
- "name",
- "folder"
- ]
-}
-```
+The only file-based data type exposed for BLOBS data is `File`, which describes an arbitrary file in a folder. The file's metadata will be describes in the JSON part of the payload, with the file schema.
### CALENDAR
@@ -427,120 +238,9 @@ The CALENDAR vertical describes calendars and events on those calendars.
Calendars are conventionally imported before the events associated with them.
-All data exposed by the CALENDER vertical is encoded as a basic data type.
+All data exposed by the CALENDER vertical is encoded as a basic data type with the
+calendar schema.
-```json
-{
- "$schema": "https://json-schema.org/draft/2020-12/schema",
- "$defs": {
- "CalendarEventTime": {
- "type": "object",
- "properties": {
- "dateOnly": {
- "type": "boolean"
- },
- "dateTime": {
- "type": "string",
- "format": "date-time"
- },
- "@type": {
- "const": "CalendarEventModel$CalendarEventTime"
- }
- },
- "required": [
- "@type",
- "dateTime"
- ]
- }
- },
- "anyOf": [
- {
- "type": "object",
- "properties": {
- "description": {
- "type": "string"
- },
- "id": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "@type": {
- "const": "Calendar"
- }
- },
- "required": [
- "@type",
- "name",
- "id"
- ]
- },
- {
- "type": "object",
- "properties": {
- "attendees": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "displayName": {
- "type": "string"
- },
- "email": {
- "type": "string"
- },
- "optional": {
- "type": "boolean"
- },
- "@type": {
- "const": "CalendarAttendeeModel"
- }
- },
- "required": [
- "@type"
- ]
- }
- },
- "calendarId": {
- "type": "string"
- },
- "endTime": {
- "$ref": "#/$defs/CalendarEventTime"
- },
- "location": {
- "type": "string"
- },
- "notes": {
- "type": "string"
- },
- "recurrenceRule": {
- "type": "object",
- "properties": {
- "exDate": {
- "type": "object"
- }
- }
- },
- "startTime": {
- "$ref": "#/$defs/CalendarEventTime"
- },
- "title": {
- "type": "string"
- },
- "@type": {
- "const": "CalendarEvent"
- }
- },
- "required": [
- "@type",
- "calendarId",
- "title"
- ]
- }
- ]
-}
-```
### SOCIAL-POSTS
@@ -548,167 +248,14 @@ Endpoint: `/social-posts`
The SOCIAL-POSTS vertical represents posts made by the user on a social media platform.
-Only the `SocialActivity` data type is exposed by the SOCIAL-POSTS vertical, which is a basic data type.
+Only the `SocialActivity` data type is exposed by the SOCIAL-POSTS vertical, see the Social Posts schema.
-```json
-{
- "$schema": "https://json-schema.org/draft/2020-12/schema",
- "type": "object",
- "properties": {
- "activity": {
- "type": "object",
- "properties": {
- "attachments": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "content": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "type": {
- "type": "string",
- "enum": [
- "LINK",
- "IMAGE",
- "VIDEO"
- ]
- },
- "url": {
- "type": "string"
- },
- "@type": {
- "const": "SocialActivityAttachment"
- }
- },
- "required": [
- "@type",
- "name"
- ]
- }
- },
- "content": {
- "type": "string"
- },
- "id": {
- "type": "string"
- },
- "location": {
- "type": "object",
- "properties": {
- "latitude": {
- "type": "number"
- },
- "longitude": {
- "type": "number"
- },
- "name": {
- "type": "string"
- },
- "@type": {
- "const": "SocialActivityLocation"
- }
- },
- "required": [
- "@type",
- "latitude",
- "longitude"
- ]
- },
- "published": {
- "type": "string",
- "format": "date-time"
- },
- "title": {
- "type": "string"
- },
- "type": {
- "type": "string",
- "enum": [
- "CHECKIN",
- "POST",
- "NOTE"
- ]
- },
- "url": {
- "type": "string"
- },
- "@type": {
- "const": "SocialActivityModel"
- }
- },
- "required": [
- "@type",
- "id",
- "content"
- ]
- },
- "metadata": {
- "type": "object",
- "properties": {
- "actor": {
- "type": "object",
- "properties": {
- "id": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "url": {
- "type": "string"
- },
- "@type": {
- "const": "SocialActivityActor"
- }
- },
- "required": [
- "@type",
- "id"
- ]
- },
- "@type": {
- "const": "SocialActivityMetadata"
- }
- },
- "required": [
- "@type"
- ]
- },
- "@type": {
- "const": "SocialActivity"
- }
- },
- "required": [
- "@type",
- "activity"
- ]
-}
-```
### Endpoint Errors
-If there is an error importing an item on any endpoint, the relevant HTTP response code (40x, 50x) should be set, and a JSON encoded response body with the following schema should be sent.
+If there is an error importing an item on any endpoint, the relevant HTTP response code (40x, 50x) should be set, and a JSON encoded response body with the error schema should be sent.
-```json
-{
- "type": "object",
- "properties": {
- "error": {
- "type": "string"
- },
- "error_description": {
- "type": "string"
- }
- },
- "required": [
- "error"
- ]
-}
-```
The combination of the HTTP response code and `error` field can be used to encode for specific failure modes; see [Token Refresh](#token-refresh) & [Destination Full](#destination-full) below.
diff --git a/extensions/data-transfer/portability-data-transfer-generic/media-schema.json b/extensions/data-transfer/portability-data-transfer-generic/album-schema.json
similarity index 69%
rename from extensions/data-transfer/portability-data-transfer-generic/media-schema.json
rename to extensions/data-transfer/portability-data-transfer-generic/album-schema.json
index 9a5ea6d1b..a6808d1bf 100644
--- a/extensions/data-transfer/portability-data-transfer-generic/media-schema.json
+++ b/extensions/data-transfer/portability-data-transfer-generic/album-schema.json
@@ -1,6 +1,7 @@
{
"$schema" : "https://json-schema.org/draft/2020-12/schema",
- "$id": "https://id.schemas.pub/org/dtinit.org/dtp/media-0.1.0",
+ "$id": "https://id.schemas.pub/o/dtinit.org/dtp/album-schema",
+ "title": "Schema for Album metadata in data-transfer-project generic endpoints",
"type": "object",
"properties": {
"description": {
diff --git a/extensions/data-transfer/portability-data-transfer-generic/calendar-schema.json b/extensions/data-transfer/portability-data-transfer-generic/calendar-schema.json
index 0d1417090..bf963ace7 100644
--- a/extensions/data-transfer/portability-data-transfer-generic/calendar-schema.json
+++ b/extensions/data-transfer/portability-data-transfer-generic/calendar-schema.json
@@ -1,5 +1,7 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://id.schemas.pub/o/dtinit.org/dtp/calendar-schema",
+ "title": "Schema for Calendar object info in data-transfer-project generic endpoints",
"$defs": {
"CalendarEventTime": {
"type": "object",
diff --git a/extensions/data-transfer/portability-data-transfer-generic/error-schema.json b/extensions/data-transfer/portability-data-transfer-generic/error-schema.json
index 9da19ff3c..13907e292 100644
--- a/extensions/data-transfer/portability-data-transfer-generic/error-schema.json
+++ b/extensions/data-transfer/portability-data-transfer-generic/error-schema.json
@@ -1,4 +1,7 @@
{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://id.schemas.pub/o/dtinit.org/dtp/error-schema",
+ "title": "Schema for Album metadata in data-transfer-project generic endpoints",
"type": "object",
"properties": {
"error": {
diff --git a/extensions/data-transfer/portability-data-transfer-generic/file-schema.json b/extensions/data-transfer/portability-data-transfer-generic/file-schema.json
index d7df92d5d..c9f8a2152 100644
--- a/extensions/data-transfer/portability-data-transfer-generic/file-schema.json
+++ b/extensions/data-transfer/portability-data-transfer-generic/file-schema.json
@@ -1,5 +1,7 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://id.schemas.pub/o/dtinit.org/dtp/file-schema",
+ "title": "Schema for file (blob) metadata in data-transfer-project generic endpoints",
"type": "object",
"properties": {
"dateModified": {
diff --git a/extensions/data-transfer/portability-data-transfer-generic/folder-schema.json b/extensions/data-transfer/portability-data-transfer-generic/folder-schema.json
index add35d3d8..c42e470c0 100644
--- a/extensions/data-transfer/portability-data-transfer-generic/folder-schema.json
+++ b/extensions/data-transfer/portability-data-transfer-generic/folder-schema.json
@@ -1,5 +1,7 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://id.schemas.pub/o/dtinit.org/dtp/folder-schema",
+ "title": "Schema for folder metadata in data-transfer-project generic endpoints",
"type": "object",
"properties": {
"path": {
diff --git a/extensions/data-transfer/portability-data-transfer-generic/payload-schema.json b/extensions/data-transfer/portability-data-transfer-generic/payload-schema.json
index 212cdf7a8..c1eb0ba87 100644
--- a/extensions/data-transfer/portability-data-transfer-generic/payload-schema.json
+++ b/extensions/data-transfer/portability-data-transfer-generic/payload-schema.json
@@ -1,5 +1,7 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://id.schemas.pub/o/dtinit.org/dtp/payload-schema",
+ "title": "Schema for payload wrapper in data-transfer-project generic endpoints",
"type": "object",
"properties": {
"apiVersion": {
@@ -9,9 +11,14 @@
"type": "object",
"description": "The inner payload, which contains data from one of the described data verticals",
"minProperties": 1,
- "anyOf": [{
- "$ref": "media-schema.json"
- }]
+ "anyOf": [
+ { "$ref": "album-schema" },
+ { "$ref": "calendar-schema" },
+ { "$ref": "file-schema" },
+ { "$ref": "folder-schema" },
+ { "$ref": "photo-and-video-schema" },
+ { "$ref": "social-posts-schema" }
+ ]
},
"schemaSource": {
"type": "string",
diff --git a/extensions/data-transfer/portability-data-transfer-generic/photo-and-video-schema.json b/extensions/data-transfer/portability-data-transfer-generic/photo-and-video-schema.json
index 90031e189..f477f4128 100644
--- a/extensions/data-transfer/portability-data-transfer-generic/photo-and-video-schema.json
+++ b/extensions/data-transfer/portability-data-transfer-generic/photo-and-video-schema.json
@@ -1,5 +1,7 @@
{
"$schema" : "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://id.schemas.pub/o/dtinit.org/dtp/photo-and-video-schema",
+ "title": "Schema for photo and video metadata in data-transfer-project generic endpoints",
"$defs": {
"FavoriteInfo": {
"type": "object",
diff --git a/extensions/data-transfer/portability-data-transfer-generic/media-payload-example.json b/extensions/data-transfer/portability-data-transfer-generic/social-post-payload-example.json
similarity index 79%
rename from extensions/data-transfer/portability-data-transfer-generic/media-payload-example.json
rename to extensions/data-transfer/portability-data-transfer-generic/social-post-payload-example.json
index 0463ab3f2..01a62207c 100644
--- a/extensions/data-transfer/portability-data-transfer-generic/media-payload-example.json
+++ b/extensions/data-transfer/portability-data-transfer-generic/social-post-payload-example.json
@@ -3,20 +3,20 @@
"schemaSource": ".../SocialPostsSerializer.java",
"apiVersion": "0.1.0",
"payload": {
- "@type": "SocialActivityData",
+ "@type": "SocialActivity",
"metadata": {
"@type": "SocialActivityMetadata",
"actor": {
"@type": "SocialActivityActor",
"id": "321",
"name": "Steve",
- "url": null
+ "url": "http://example.org/actor/321"
}
},
"activity": {
"@type": "SocialActivityModel",
"id": "456",
- "published": 1731604863.845677,
+ "published": "1731604863.845677",
"type": "NOTE",
"attachments": [
{
@@ -24,7 +24,7 @@
"type": "IMAGE",
"url": "foo.com",
"name": "Foo",
- "content": null
+ "content": "Example content"
}
],
"location": {
@@ -35,7 +35,7 @@
},
"title": "Hello world!",
"content": "Hi there",
- "url": null
+ "url": "http://example.org/post/foo"
}
}
}
\ No newline at end of file
diff --git a/extensions/data-transfer/portability-data-transfer-generic/social-posts-schema.json b/extensions/data-transfer/portability-data-transfer-generic/social-posts-schema.json
index 4f50a3a17..29fbf837a 100644
--- a/extensions/data-transfer/portability-data-transfer-generic/social-posts-schema.json
+++ b/extensions/data-transfer/portability-data-transfer-generic/social-posts-schema.json
@@ -1,5 +1,7 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://id.schemas.pub/o/dtinit.org/dtp/social-posts-schema",
+ "title": "Schema for social post object data in data-transfer-project generic endpoints",
"type": "object",
"properties": {
"activity": {