From 1471248132097db92cad27ea440ed997229d8055 Mon Sep 17 00:00:00 2001
From: Natalia Portillo <claunia@claunia.com>
Date: Sun, 5 Oct 2025 04:49:19 +0100
Subject: [PATCH] Add Aaru Metadata JSON block documentation

---
 docs/spec/blocks/aaru_metadata.adoc | 25 +++++++++++++++++++++++++
 docs/spec/spec.adoc                 |  4 ++++
 docs/spec/version_history.adoc      |  4 +++-
 3 files changed, 32 insertions(+), 1 deletion(-)
 create mode 100644 docs/spec/blocks/aaru_metadata.adoc

diff --git a/docs/spec/blocks/aaru_metadata.adoc b/docs/spec/blocks/aaru_metadata.adoc
new file mode 100644
index 0000000..fe210eb
--- /dev/null
+++ b/docs/spec/blocks/aaru_metadata.adoc
@@ -0,0 +1,25 @@
+=== Aaru Metadata JSON Block (`JSMD`)
+
+This block header signifies the inclusion of an embedded Aaru metadata JSON sidecar.
+The contents of the JSON are preserved in their original form and are not parsed, interpreted, or validated by the format implementation.
+
+==== Structure Definition
+
+[source,c]
+#define METADATA_JSON_MAGIC 0x444D534A
+/**Header for the Aaru Metadata JSON block */
+typedef struct AaruMetadataJsonBlock
+{
+    /**Identifier, <see cref="BlockType.AaruMetadataJsonBlock" /> */
+    uint32_t identifier;
+    uint32_t length;
+} AaruMetadataJsonBlock;
+
+==== Field Descriptions
+
+[cols="2,2,2,6",options="header"]
+|===
+|Type|Size|Name|Description
+|uint32|4 bytes|identifier|The Aaru metadata JSON identifier, always `JSMD`
+|uint32|4 bytes|length|The size in bytes of the embedded Aaru metadata JSON that follows this header.
+|===
\ No newline at end of file
diff --git a/docs/spec/spec.adoc b/docs/spec/spec.adoc
index a9d9ae7..d1c1177 100644
--- a/docs/spec/spec.adoc
+++ b/docs/spec/spec.adoc
@@ -74,6 +74,10 @@ include::blocks/tracks.adoc[]
 
 <<<
 
+include::blocks/aaru_metadata.adoc[]
+
+<<<
+
 include::blocks/cicm.adoc[]
 
 <<<
diff --git a/docs/spec/version_history.adoc b/docs/spec/version_history.adoc
index ce30bb8..8701ecb 100644
--- a/docs/spec/version_history.adoc
+++ b/docs/spec/version_history.adoc
@@ -75,7 +75,7 @@ Define twin sector table.
 
 Add annex explaining the meaning and relationship between user, bitstream and flux data.
 
-| 31 July 2025
+| 5 October 2025
 | 2.0df
 | Draft
 | Natalia Portillo
@@ -96,4 +96,6 @@ Clarify deduplication table size type.
 Clarify deduplication table sector status.
 
 Add encrypted and decrypted sector status.
+
+Add Aaru Metadata JSON.
 |===