Added jot protocol serializer skeleton

ical4j · Jan 17, 2024 · f7bfd5e · f7bfd5e
1 parent 6b9d640
commit f7bfd5e
Show file tree

Hide file tree

Showing 10 changed files with 166 additions and 3 deletions.
diff --git a/docs/serializer/jotp/availability.md b/docs/serializer/jotp/availability.md
@@ -0,0 +1,2 @@
+# iCal4j Serializer - JOT Availability
+
diff --git a/docs/serializer/jotp/calendar.md b/docs/serializer/jotp/calendar.md
@@ -0,0 +1,123 @@
+# iCal4j Serializer - JOT Calendar
+
+The JOT Calendar serializer may be used to create or update Calendar object properties.
+
+## Overview
+
+An iCalendar object may include the following properties once:
+
+* UID
+* LAST-MODIFIED
+* URL
+* REFRESH
+* SOURCE
+* COLOR
+
+An iCalendar object may include the following properties multiple times:
+
+* NAME
+* DESCRIPTION
+* CATEGORIES
+* IMAGE
+
+An example using all of these properties may look like this:
+
+```json
+{
+  "uid": "1234-abcd",
+  "last-modified": "20240117T105900Z",
+  "url": "https://example.com/public_holidays",
+  "refresh-interval": "P1W",
+  "source": "https://example.com/public_holidays.ics",
+  "color": "orange",
+  "name": ["International Public Holidays"],
+  "description": ["Globally recognised public holidays"],
+  "categories": ["holidays", "global"],
+  "image": ["https://example.com/images/holiday.png"]
+}
+```
+
+## HTTP Payloads
+
+Such a payload may be used to add, remove or update properties. For example, used in conjunction with HTTP verbs
+full CRUD operations may be implemented:
+
+### Create a calendar
+
+```json
+POST https://api.example.com/v1/calendars
+{
+  "name": ["International Public Holidays"],
+  "description": ["Globally recognised public holidays"],
+  "categories": ["holidays"]
+}
+
+RESPONSE:
+
+{
+  "uid": "1234-abcd",
+  "last-modified": "20240117T105900Z",
+  "name": ["International Public Holidays"],
+  "description": ["Globally recognised public holidays"],
+  "categories": ["holidays"]
+}
+```
+
+### Update a calendar by adding additional properties
+
+```json
+POST https://api.example.com/v1/calendars/1234-abcd
+{
+  "categories": ["global"]
+}
+
+RESPONSE:
+
+{
+  "uid": "1234-abcd",
+  "last-modified": "20240117T105900Z",
+  "name": ["International Public Holidays"],
+  "description": ["Globally recognised public holidays"],
+  "categories": ["holidays", "global"]
+}
+```
+
+### Update a calendar by removing existing properties
+
+```json
+DELETE https://api.example.com/v1/calendars/1234-abcd
+{
+  "categories": ["global"]
+}
+
+RESPONSE:
+
+{
+  "uid": "1234-abcd",
+  "last-modified": "20240117T105900Z",
+  "name": ["International Public Holidays"],
+  "description": ["Globally recognised public holidays"],
+  "categories": ["holidays"]
+}
+```
+
+### Replace all properties
+
+```json
+PUT https://api.example.com/v1/calendars/1234-abcd
+{
+  "uid": "1234-abcd",
+  "last-modified": "20240117T105900Z",
+  "name": ["International Public Holidays"],
+  "description": ["Globally recognised public holidays"]
+}
+
+RESPONSE:
+
+{
+  "uid": "1234-abcd",
+  "last-modified": "20240117T105900Z",
+  "name": ["International Public Holidays"],
+  "description": ["Globally recognised public holidays"]
+}
+```
diff --git a/docs/serializer/jotp/card.md b/docs/serializer/jotp/card.md
@@ -0,0 +1,2 @@
+# iCal4j Serializer - JOT Card
+
diff --git a/docs/serializer/jotp/event.md b/docs/serializer/jotp/event.md
@@ -0,0 +1,2 @@
+# iCal4j Serializer - JOT Event
+
diff --git a/docs/serializer/jotp/index.md b/docs/serializer/jotp/index.md
@@ -0,0 +1,22 @@
+# iCal4j Serializer - JOT Protocol
+
+The JOT Protocol is derived JSON format that may be used to construct and modify iCalendar and vCard objects.
+
+## Overview
+
+JOT does not provide a lossless complete representation of iCalendar and vCard, but rather is used to convey
+concise information used to construct and modify data as would be commonly found in a REST-ful API.
+
+For example, if we want to create a new event, rather than providing a complete iCalendar object (as would be
+the case with xCal/jCal/JSCalendar, etc.) we can provide just the required information:
+
+```json
+{
+  "summary": "Monthly financial debrief",
+  "rrule": "FREQ=MONTHLY;BYDAY=-1FR"
+}
+```
+
+Obviously there is a lot of missing information required to construct a complete iCalendar object, but the
+serializer implementation may be used to fill in those blanks.
+
diff --git a/docs/serializer/jotp/journal.md b/docs/serializer/jotp/journal.md
@@ -0,0 +1,2 @@
+# iCal4j Serializer - JOT Journal
+
diff --git a/docs/serializer/jotp/todo.md b/docs/serializer/jotp/todo.md
@@ -0,0 +1,2 @@
+# iCal4j Serializer - JOT ToDo
+
diff --git a/docs/serializer/json.md b/docs/serializer/json.md
@@ -1,3 +1,3 @@
-# iCal4j Serializer - JSON
+# iCal4j Serializer - jCal/jCard
 
 iCal4j support serialization to and from the jCal format, which is a direct translation of iCalendar to JSON.
diff --git a/docs/serializer/xml.md b/docs/serializer/xml.md
@@ -1,3 +1,3 @@
-# iCal4j Serializer - XML
+# iCal4j Serializer - xCal/xCard
 
 iCal4j support serialization to and from the xCal format, which is a direct translation of iCalendar to XML.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -152,10 +152,18 @@ nav:
     - JSON: serializer/json.md
     - JSON-LD: serializer/json-ld.md
     - JMAP: serializer/jmap.md
+    - JOT:
+      - Overview: serializer/jotp/index.md
+      - Calendar: serializer/jotp/calendar.md
+      - Event: serializer/jotp/event.md
+      - ToDo: serializer/jotp/todo.md
+      - Journal: serializer/jotp/journal.md
+      - Availability: serializer/jotp/availability.md
+      - Card: serializer/jotp/card.md
   - Connector:
     - Overview: connector/index.md
     - Local: connector/local.md
-    - WebDAV: connector/dav.md
+    - DAV: connector/dav.md
   - Integration:
     - Overview: integration/index.md
     - Email: integration/email.md