From d301b64ad5f366bdeceabe047e0d778257b0b0fe Mon Sep 17 00:00:00 2001 From: Brandon Liu Date: Wed, 27 Dec 2023 09:13:02 +0800 Subject: [PATCH] spec v3.4 (#313) * add details on leaf directory ordering and entry length > 0. --- spec/v3/CHANGELOG.md | 4 ++++ spec/v3/spec.md | 4 +++- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/spec/v3/CHANGELOG.md b/spec/v3/CHANGELOG.md index 126bc65..520c8c6 100644 --- 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 index 005f69b..9e76034 100644 --- 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.