Relative serialization path hashing and aliasing

Abstract

Overview of the path shortening principles of the Sitecore Content Serialization (SCS) system.

The Sitecore Content Serialization (SCS) system uses hashing to shorten paths that are too long for your file system. It also offers human readable aliases of hashes.

The file system path of serialized content items is determined by one absolute and three relative paths:

  • The absolute base path. This is where your project is located in your file system.

  • The relative serialization path. This is where the SCS system serializes content items.

  • The relative include path. This is what you have named the folder that your content items must be stored in.

  • The relative content item path. This is the path of the content items in a Sitecore instance.

The SCS system concatenates the base path, the serialization path, the include path, and the content item path into a file system path and file name.

For example, consider these four paths:

  • C:\Users\Peter\Sitecore\Project\src\Sites\ is the base path.

  • serialization\ is the serialization path.

  • content\ is the include path.

  • Home\Products\Toys\Ball.yml is the content item path.

The SCS system concatenates the paths into the following file system path and file name:

C:\Users\Peter\Sitecore\Project\src\Sites\serialization\content\Home\Products\Toys\Ball.yml

This path and file name are not too long for any modern file system, but content workers can create content item paths that violate your file system's maximum path and file name lengths. To avoid this situation, your can configure the maximum content item path length.

The SCS system respects this maximum length by:

  • Removing content item path segments until the content item path is short enough.

  • Hashing the removed content item path segments into a single hash value.

  • Concatenating the hash value with the remaining content item path.

For example, if the maximum content item path length is set to 20, and you want to serialize the content item path /Home/Products/Toys/Ball, which is 24 characters long, the SCS system hashes /Home/Products/Toys/ to a single value and concatenates it with Ball.yml to C:\Users\Peter\Sitecore\Project\src\Sites\serialization\content\<hash value>\Ball.yml.

If you find the hash values too unfriendly for human reading, you can add path aliases to your rules. A path alias is a custom hash value that you define.

For example, to hash the content item path /Home/Producs/Toys/Ball into hptoys/Ball, you add this alias to your rule:

"rules": [
  {
    "path": "/Home/Products/Toys/Ball",
    "alias": "hptoys"
  }
]

The SCS system now stores the serialized content item in C:\Users\Peter\Sitecore\Project\src\Sites\serialization\content\hptoys\Ball.yml.