Skip to main content

How to build a PURL

How to build a PURL string from its components​

Building a PURL ASCII string works from left to right, from type to subpath.

Note: some extra type-specific normalizations are required.

To build a PURL string from its components:

  • Start a PURL string with the scheme as a lowercase ASCII string.

  • Append the type string to the PURL as an unencoded lowercase ASCII string.

  • Append '/' to the PURL.

  • If the namespace is not empty:

    • Strip the namespace from leading and trailing '/'.
    • Split on '/' as segments.
    • Apply type-specific normalization to each segment if needed.
    • UTF-8-encode each segment if needed in your programming language.
    • Percent-encode each segment.
    • Join the segments with '/'.
    • Append this to the PURL.
    • Append '/' to the PURL.
    • Strip the name from leading and trailing '/'.
    • Apply type-specific normalization to the name if needed.
    • UTF-8-encode the name if needed in your programming language.
    • Append the percent-encoded name to the PURL.

  • If the namespaceis empty:

    • Apply type-specific normalization to the name if needed.
    • UTF-8-encode the name if needed in your programming language.
    • Append the percent-encoded name to the PURL.

  • If the version is not empty:

    • Append '@' to the PURL.
    • UTF-8-encode the version if needed in your programming language.
    • Append the percent-encoded version to the PURL.

  • If the qualifiers are not empty and not composed only of key/value pairs where the value is empty:

    • Append '?' to the PURL.

    • Build a list from all key/value pairs:

      • Discard any pair where the value is empty.
      • UTF-8-encode each value if needed in your programming language.
      • If the key is 'checksum' and this is a list of checksums join this list with a ',' to create this qualifier value.
      • Create a string by joining the lowercase key, the equal '=' sign and the percent-encoded value to create a qualifier.

    • Sort this list of qualifier strings lexicographically.

    • Join this list of qualifier strings with a '&' ampersand

    • Append this string to the PURL.

  • If the subpath is not empty and not composed only of empty, '.' and '..' segments:

    • Append '#' to the PURL.
    • Divide the subpath into segments using the path delimiter of your environment (operating system, file system, etc.).
    • Discard empty, '.' and '..' segments.
    • Percent-encode each segment.
    • UTF-8-encode each segment if needed in your programming language.
    • Join the segments with '/'.
    • Append this to the PURL.