spec v3.4 (#313)

* add details on leaf directory ordering and entry length > 0.
protomaps · Dec 27, 2023 · d301b64 · d301b64
1 parent dd76720
commit d301b64
Show file tree

Hide file tree

Showing 2 changed files with 7 additions and 1 deletion.
diff --git a/spec/v3/CHANGELOG.md b/spec/v3/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Changelog
 
+## Version 3.4
+- Clarify that entry lengths must be > 0.
+- Add details about ordering of leaf directories.
+
 ## Version 3.3
 - Narrow `clustered` meaning: first tile entry must be offset 0.
 - Add language discouraging the creation of nested leaf directories.

diff --git a/spec/v3/spec.md b/spec/v3/spec.md
@@ -262,6 +262,8 @@ A directory is simply a list of entries. Each entry describes either where a spe
 The number of entries in the root directory and in the leaf directories is left to the implementation and can vary depending on what the writer has optimized for (cost, bandwidth, latency, etc.).
 However, the size of the header plus the compressed size of the root directory MUST NOT exceed 16384 bytes to allow latency-optimized clients to retrieve the root directory in its entirety. Therefore, the **maximum compressed size of the root directory is 16257 bytes** (16384 bytes - 127 bytes). A sophisticated writer might need several attempts to optimize this.
 
+The order of leaf directories SHOULD be ascending by starting TileID.
+
 It is discouraged to create an archive with more than one level of leaf directories. If you are implementing a writer and discover this need, please open an issue.
 
 ### 4.1 Directory Entries
@@ -292,7 +294,7 @@ The TileID corresponds to a cumulative position on the series of [Hilbert curves
 Specifies the offset of the first byte of the tile or leaf directory. This address offset is relative to the first byte of the _tile data section_ for tile entries and relative to the first byte of the _leaf directories section_ for leaf directory entries.
 
 #### Length
-Specifies the number of bytes of this tile or leaf directory. This size always indicates the compressed size, if the tile or leaf directory is compressed.
+Specifies the number of bytes of this tile or leaf directory. This size always indicates the compressed size, if the tile or leaf directory is compressed. The length MUST be greater than 0.
 
 #### RunLength
 Specifies the number of tiles for which this entry is valid. A run length of `0` means that this entry is for a leaf directory and not for a tile.