From 79d1524af001cd985cafd6c621fd3faf11dc126e Mon Sep 17 00:00:00 2001
From: Jesse Wierzbinski <contact@cpluspatch.com>
Date: Mon, 13 May 2024 08:36:37 -1000
Subject: [PATCH] =?UTF-8?q?feat:=20=E2=9C=A8=20Clarify=20number=20types=20?=
 =?UTF-8?q?for=20strictly-typed=20languages=20such=20as=20Rust?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: April John <30842467+CutestNekoAqua@users.noreply.github.com>
---
 docs/extensions/polls.md          |  6 +++---
 docs/objects/publications.md      |  2 +-
 docs/spec.md                      |  8 ++++++++
 docs/structures/collection.md     |  2 +-
 docs/structures/content-format.md | 12 +++++-------
 5 files changed, 18 insertions(+), 12 deletions(-)

diff --git a/docs/extensions/polls.md b/docs/extensions/polls.md
index a697efb..eb3b7e9 100644
--- a/docs/extensions/polls.md
+++ b/docs/extensions/polls.md
@@ -226,7 +226,7 @@ The server **MAY** send a `GET` request to the poll's Publication URI to update
 interface Poll extends Extension {
     extension_type: "org.lysand:polls/Poll";
     options: ContentFormat[];
-    votes: number[];
+    votes: number[]; // unsigned 64-bit integer
     multiple_choice?: boolean;
     expires_at: string;
 }
@@ -236,7 +236,7 @@ interface Poll extends Extension {
 interface Vote extends Extension {
     extension_type: "org.lysand:polls/Vote";
     poll: string;
-    option: number;
+    option: number; // unsigned 64-bit integer
 }
 ```
 
@@ -244,6 +244,6 @@ interface Vote extends Extension {
 interface VoteResult extends Extension {
     extension_type: "org.lysand:polls/VoteResult";
     poll: string;
-    votes: number[];
+    votes: number[]; // unsigned 64-bit integer
 }
 ```
diff --git a/docs/objects/publications.md b/docs/objects/publications.md
index 36b3f20..ed440de 100644
--- a/docs/objects/publications.md
+++ b/docs/objects/publications.md
@@ -295,7 +295,7 @@ interface Publication extends Entity {
         "org.lysand:polls"?: {
             poll: {
                 options: ContentFormat[];
-                votes: number[];
+                votes: number[]; // unsigned 64-bit integer
                 multiple_choice?: boolean;
                 expires_at: string;
             };
diff --git a/docs/spec.md b/docs/spec.md
index 17abcc6..de52377 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -34,6 +34,14 @@ The words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are us
 
 Servers **MUST** reject any requests that fail to respect the Lysand specification in any way. This includes, but is not limited to, incorrect JSON object handling, incorrect HTTP headers, and incorrect URI normalization.
 
+## For strictly-typed languages (e.g. Rust)
+
+All numbers are to be treated as 64-bit integer or floats (depending on whether a valid value would be int or float). If a valid value cannot be negative, it must also be treated as unsigned.
+
+Examples:
+- A `size` (bytes) property on a file object should be treated as an unsigned 64-bit integer.
+- A `duration` property on a video object should be treated as an unsigned 64-bit float.
+
 ## HTTP
 
 All HTTP request and response bodies **MUST** be encoded as UTF-8 JSON, with the `Content-Type` header set to `application/json; charset=utf-8`. Appropriate signatures must be included in the `Signature` header for **every request and response**.
diff --git a/docs/structures/collection.md b/docs/structures/collection.md
index cd7d801..9b698e4 100644
--- a/docs/structures/collection.md
+++ b/docs/structures/collection.md
@@ -8,7 +8,7 @@ Here's how a Collections can be represented in TypeScript:
 interface Collections<T> {
     first: string;
     last: string;
-    total_count: number;
+    total_count: number; // unsigned 64-bit integer
     author: string;
     next?: string;
     prev?: string;
diff --git a/docs/structures/content-format.md b/docs/structures/content-format.md
index 12a5398..af507d3 100644
--- a/docs/structures/content-format.md
+++ b/docs/structures/content-format.md
@@ -7,19 +7,17 @@ interface ContentFormat {
     [contentType: string]: {
         content: string;
         description?: string;
-        size?: number;
+        size?: number; // unsigned 64-bit integer
         hash?: {
-            md5?: string;
-            sha1?: string;
             sha256?: string;
             sha512?: string;
             [key: string]: string | undefined;
         };
         blurhash?: string;
-        fps?: number;
-        width?: number;
-        height?: number;
-        duration?: number;
+        fps?: number; // unsigned 64-bit integer
+        width?: number; // unsigned 64-bit integer
+        height?: number; // unsigned 64-bit integer
+        duration?: number; // unsigned 64-bit integer
     }
 }
 ```